create-bcp-app 0.2.17 → 0.2.19

package/README.md

@@ -10,9 +10,7 @@ npm run dev
 
 ## Project-local BCP CLI
 
-`create-bcp-app` installs BCP Framework as a project-local dependency. It does not install the framework CLI globally.
-
-Generated npm scripts use `bcp` because npm places `node_modules/.bin` on the script `PATH`:
+`create-bcp-app` installs BCP Framework as a project-local dependency. Generated npm scripts use the local CLI:
 
 ```json
 {
@@ -28,7 +26,7 @@ Generated npm scripts use `bcp` because npm places `node_modules/.bin` on the sc
 }
 ```
 
-For direct PowerShell usage, prefer the collision-free local alias:
+For direct PowerShell usage, prefer the collision-free alias:
 
 ```powershell
 npm exec -- bcp-framework --version
@@ -66,17 +64,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.2.17` target:
+Example for the `0.2.19` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.17",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.19",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.17"
+    "version": "0.2.19"
   },
   "packageManager": "npm",
   "presets": {
@@ -88,7 +86,7 @@ Example for the `0.2.17` target:
 }
 ```
 
-This manifest records scaffold identity only. It must not contain secrets and should normally be committed to source control.
+This manifest records scaffold identity only. Do not place secrets in it.
 
 ## Database presets
 
@@ -104,71 +102,23 @@ For MySQL, PostgreSQL and SQLite, generated `lib/database.ts` exposes BCP databa
 
 ## Authentication and security
 
-The JWT Cookie preset creates `lib/auth.ts` and starter auth routes. BCP `0.2.5+` supports optional revocable server-side auth state, while `0.2.6+` adds permission/policy authorization plus same-origin/CSRF helpers.
+The JWT Cookie preset creates starter authentication code. BCP supports revocable session stores, permission/policy authorization, route guards and same-origin/CSRF helpers.
 
-## Background jobs and scheduling
+## Background jobs, workflows and events
 
 ```ts
 import {
     createJobQueue,
     createJobScheduler,
 } from "bcp/jobs";
-
-export const jobs =
-    createJobQueue();
-
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-    });
-```
-
-`0.2.10+` adds visibility leases, heartbeat renewal, stale-running recovery, DLQ/requeue, retention cleanup and Redis-compatible durable adapters.
-
-## Workflow orchestration — 0.2.11+
-
-```ts
 import {
     createWorkflow,
 } from "bcp/workflow";
-
-export const onboarding =
-    createWorkflow(
-        "user.onboarding",
-        workflow => {
-            workflow.step(
-                "profile",
-                createProfile
-            );
-            workflow.delay(
-                "cooldown",
-                1_000
-            );
-        }
-    );
 ```
 
-## Transactional Outbox & Events — 0.2.12+
-
-```ts
-await db.transaction(
-    async tx => {
-        await tx.execute(
-            "INSERT INTO orders ..."
-        );
-
-        await outbox.publish(
-            tx,
-            "order.created",
-            {
-                orderId: 42,
-            }
-        );
-    }
-);
-```
+Durable Redis-compatible queues/schedules, workflow orchestration and transactional outbox/event delivery are available without forcing a Redis client dependency.
 
-## Realtime Platform — 0.2.13+
+## Realtime
 
 ```ts
 import {
@@ -179,187 +129,151 @@ export const realtime =
     createRealtime();
 ```
 
-BCP does not install a WebSocket library. Adapt your selected provider to `RealtimeSocket`. SSE is available directly through `realtime.sse()`.
+BCP does not install a WebSocket server library. Applications adapt their provider to `RealtimeSocket`; SSE is built in.
 
-## Testing Platform — 0.2.14+
+## Testing
 
-```ts
-import {
-    createRouteTestHandler,
-    createTestApp,
-    expectResponse,
-} from "bcp/testing";
-
-const app =
-    createTestApp({
-        handler:
-            createRouteTestHandler({
-                GET() {
-                    return {
-                        ok: true,
-                    };
-                },
-            }),
-    });
+`bcp/testing` provides request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime test harnesses and does not require Jest or Vitest.
 
-await expectResponse(
-    await app.get("/api/health")
-)
-    .status(200)
-    .json({
-        ok: true,
-    });
-```
+## Plugins
 
-BCP testing helpers are runner-neutral and can be used with Node `node:test`, Vitest, Jest or another runner.
+`bcp/plugins` provides dependency ordering, module composition, lifecycle hooks, config parsing, shared services and async hooks.
 
-## Plugin & Module Platform — 0.2.15+
-
-```ts
-import {
-    createPluginHost,
-    definePlugin,
-} from "bcp/plugins";
-
-const databasePlugin =
-    definePlugin({
-        name: "database",
-        setup(context) {
-            context.services.provide(
-                "database",
-                db
-            );
-        },
-    });
-
-const jobsPlugin =
-    definePlugin({
-        name: "jobs",
-        requires: [
-            "database",
-        ],
-    });
-
-export const plugins =
-    createPluginHost({
-        plugins: [
-            jobsPlugin,
-            databasePlugin,
-        ],
-    });
-```
-
-## Cache Platform v2 — 0.2.16+
+## Cache Platform v2
 
 ```ts
 import {
     createCacheStore,
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
 } from "bcp/cache";
 
 export const cache =
-    createCacheStore({
-        adapter:
-            createRedisCacheAdapter({
-                client: redisClient,
-            }),
-        lock:
-            createRedisCacheLockAdapter({
-                client: redisClient,
-            }),
-    });
+    createCacheStore();
 ```
 
-BCP does not install or own the Redis client. Applications remain responsible for credentials, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
-
-## Observability Platform v3 — 0.2.17+
+Multi-instance applications can use Redis-compatible cache and lock adapters for distributed cache-fill coordination.
 
-Metrics and health remain available through the same entrypoint:
+## Observability Platform v3
 
 ```ts
 import {
-    createHealthRegistry,
-    createMetricsRegistry,
     createTracer,
 } from "bcp/observability";
-```
-
-Create a tracer:
 
-```ts
 export const tracer =
     createTracer({
         serviceName: "my-app",
     });
 ```
 
-Trace incoming HTTP requests with Middleware System v2:
+Tracing supports W3C `traceparent`, correlation IDs, request middleware, explicit carriers for jobs/workflows/events/realtime and provider-neutral exporters.
+
+## Deployment Platform v2 — 0.2.18+
+
+Use `bcp/deployment` to coordinate application resources in production:
 
 ```ts
 import {
-    createRequestTracingMiddleware,
-} from "bcp/observability";
+    createDeploymentRuntime,
+} from "bcp/deployment";
 
-export const middleware =
-    createRequestTracingMiddleware(
-        tracer
-    );
+export const deployment =
+    createDeploymentRuntime({
+        serviceName: "my-app",
+    });
 ```
 
-The middleware understands W3C `traceparent`, preserves `x-correlation-id`, creates a server span and returns the current trace headers on the response.
+Register shared dependencies before components that use them:
+
+```ts
+deployment.addResource({
+    name: "database",
+
+    async start() {
+        await db.connect();
+    },
+
+    ready() {
+        return db.status === "ready";
+    },
+
+    async stop() {
+        await db.close();
+    },
+});
+
+deployment.addResource({
+    name: "workers",
+
+    start() {
+        worker = jobs.startWorker();
+    },
 
-For jobs/workflows/events/realtime payloads use explicit trace carriers:
+    async stop() {
+        await worker.stop();
+    },
+});
+
+await deployment.start();
+```
+
+Startup follows registration order and shutdown reverses it. This naturally stops workers before database/cache/Redis connections.
+
+Readiness endpoint:
 
 ```ts
 import {
-    createTraceCarrier,
-    runWithTraceCarrier,
-} from "bcp/observability";
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
 
-const trace =
-    createTraceCarrier();
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
+    );
+}
+```
 
-await jobs.enqueue(
-    "order.process",
-    {
-        orderId,
-        trace,
-    }
-);
+Runtime identity can use:
+
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
 ```
 
-Consumer:
+Install graceful signal handling with:
 
 ```ts
-await runWithTraceCarrier(
-    payload.trace,
-    () =>
-        tracer.withSpan(
-            "job order.process",
-            handler,
-            {
-                kind: "consumer",
-            }
-        )
-);
+const removeSignals =
+    deployment.installSignalHandlers();
 ```
 
-Use `getTraceLogFields()` to add `traceId`, `spanId` and `correlationId` to structured logs.
+Default signals are `SIGTERM` and `SIGINT`.
 
-BCP does not install OpenTelemetry or a vendor APM package. Implement `TraceSpanExporter` when production spans need to be sent to an external collector.
+## Stability & API Freeze — 0.2.19
 
-## Storage providers
+`0.2.19` keeps the `0.2.x` public package surface stable before the next platform baseline.
 
-Supported presets are Local Server, Amazon S3 and Cloudflare R2. Storage credentials are server-only and must not use `BCP_PUBLIC_*` variables.
+Framework maintainers can validate the frozen contract with:
+
+```bash
+npm run api:check
+npm run release:readiness
+```
+
+Generated applications do not need to run these framework-repository release commands. Application code should continue importing documented `bcp/*` entrypoints rather than private framework source paths.
 
 ## Application packaging
 
 ```bash
+npm run build
 npm run package
 ```
 
-The deployment package excludes application `devDependencies` and project `.env` values. Supply real secrets through the deployment environment.
+The deployment package excludes application `devDependencies` and project `.env` values. Supply secrets through the deployment environment.
+
+BCP `0.2.19` prepared framework packages preserve the compiled ESM runtime map introduced by Deployment Platform v2 for the main server entrypoints including config, auth, observability, deployment, server and middleware.
 
 ## Project generators
 
@@ -387,5 +301,5 @@ npm run generate -- migration create_users
 For prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.17.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.19.tgz
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -27,113 +27,33 @@ npm run update
 
 Generated projects include `bcp.project.json` with non-secret scaffold metadata. Commit it with the project, but never put passwords, tokens or access keys in it.
 
-## Authentication — BCP 0.2.5+
+## Authentication and authorization
 
-JWT Cookie projects can opt into revocable server-side session state with `createAuth()` and `AuthSessionStore`.
+JWT Cookie projects can use `createAuth()` and optional `AuthSessionStore` revocation. Permission guards/resource policies live in `bcp/auth`; same-origin/CSRF helpers live in `bcp/server`.
 
-## Authorization & request security — BCP 0.2.6+
+## Database
 
-Use permission guards/resource policies from `bcp/auth`, and same-origin/CSRF protection from `bcp/server`. Authorization must remain server-side.
+MySQL, PostgreSQL and SQLite projects expose the BCP database platform through `bcp/database`.
 
-## Observability — BCP 0.2.7+
-
-```ts
-import {
-    createHealthRegistry,
-    createMetricsRegistry,
-} from "bcp/observability";
-```
-
-## Background jobs — BCP 0.2.8+
+## Jobs, scheduling and workflows
 
 ```ts
 import {
     createJobQueue,
-} from "bcp/jobs";
-
-export const jobs =
-    createJobQueue();
-```
-
-## Job scheduling — BCP 0.2.9+
-
-```ts
-import {
     createJobScheduler,
 } from "bcp/jobs";
-
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-    });
-```
-
-## Durable jobs — BCP 0.2.10+
-
-Workers can use visibility leases, heartbeat renewal, stale recovery and DLQ/requeue. Redis-compatible adapters are available without forcing a Redis client dependency.
-
-```ts
-const worker =
-    jobs.startWorker({
-        workerId: "worker-a",
-        concurrency: 4,
-        visibilityTimeoutMs: 30_000,
-        heartbeatIntervalMs: 10_000,
-    });
-```
-
-## Workflow orchestration — BCP 0.2.11+
-
-```ts
 import {
     createWorkflow,
 } from "bcp/workflow";
-
-export const onboarding =
-    createWorkflow(
-        "user.onboarding",
-        workflow => {
-            workflow.step(
-                "profile",
-                createProfile
-            );
-            workflow.delay(
-                "cooldown",
-                1_000
-            );
-        }
-    );
 ```
 
-Workflows support sequential/parallel steps, retries, persisted delays, compensation, run leases and optional durable queue execution.
+Durable jobs support leases, heartbeat, stale recovery and DLQ. Workflows support sequential/parallel steps, retries, persisted delays and compensation.
 
-## Transactional Outbox & Events — BCP 0.2.12+
+## Transactional events
 
-Use `bcp/events` when application data and an integration event must commit atomically in the same SQL transaction.
+Use `bcp/events` when business data and an integration event must commit in the same SQL transaction. The outbox dispatcher can deliver through durable jobs or an application publisher after commit.
 
-```ts
-await db.transaction(
-    async tx => {
-        await tx.execute(
-            "INSERT INTO orders ..."
-        );
-
-        await outbox.publish(
-            tx,
-            "order.created",
-            {
-                orderId: 42,
-            }
-        );
-    }
-);
-```
-
-After commit, `createOutboxDispatcher()` can deliver through durable jobs or a custom publisher.
-
-## Realtime Platform — BCP 0.2.13+
-
-Create a server-side realtime hub:
+## Realtime
 
 ```ts
 import {
@@ -144,252 +64,143 @@ export const realtime =
     createRealtime();
 ```
 
-Channels/rooms:
+BCP does not install a WebSocket server library. Adapt the selected provider through `RealtimeSocket`; SSE is built in.
 
-```ts
-const connection =
-    await realtime.connect();
-
-await connection.join(
-    "orders:42"
-);
-
-await realtime.broadcast(
-    "orders:42",
-    "order.updated",
-    {
-        status: "paid",
-    }
-);
-```
+## Testing
 
-BCP does not install a WebSocket server dependency. Adapt the selected provider to `RealtimeSocket`. SSE is built in through `realtime.sse()`.
+`bcp/testing` provides request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers without requiring Jest or Vitest.
 
-For multi-instance deployment, replace the memory broker/presence store with shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+## Plugins
 
-## Testing Platform — BCP 0.2.14+
+`bcp/plugins` provides reusable server-side plugins/modules, dependency ordering, lifecycle hooks, config parsing, shared services and awaited hooks.
 
-Use server-only `bcp/testing` to exercise framework contracts without adding a BCP-specific test runner.
+## Cache Platform v2
 
 ```ts
 import {
-    createRouteTestHandler,
-    createTestApp,
-    expectResponse,
-} from "bcp/testing";
-
-const app =
-    createTestApp({
-        handler:
-            createRouteTestHandler({
-                GET() {
-                    return {
-                        ok: true,
-                    };
-                },
-            }),
-    });
+    createCacheStore,
+} from "bcp/cache";
 
-await expectResponse(
-    await app.get("/api/health")
-)
-    .status(200)
-    .json({
-        ok: true,
-    });
+export const cache =
+    createCacheStore();
 ```
 
-BCP does not require Jest or Vitest; these helpers work with Node `node:test` or another runner.
+Use Redis-compatible cache/lock adapters for multi-instance cache-fill coordination when needed.
 
-## Plugin & Module Platform — BCP 0.2.15+
-
-Use `bcp/plugins` to compose reusable server-only application services with explicit dependencies.
+## Observability Platform v3
 
 ```ts
 import {
-    createPluginHost,
-    definePlugin,
-} from "bcp/plugins";
-
-const databasePlugin =
-    definePlugin({
-        name: "database",
-        setup(context) {
-            context.services.provide(
-                "database",
-                db
-            );
-        },
-    });
-
-const jobsPlugin =
-    definePlugin({
-        name: "jobs",
-        requires: [
-            "database",
-        ],
-    });
+    createTracer,
+} from "bcp/observability";
 
-export const plugins =
-    createPluginHost({
-        plugins: [
-            jobsPlugin,
-            databasePlugin,
-        ],
+export const tracer =
+    createTracer({
+        serviceName: "bcp-app",
     });
 ```
 
-Plugin startup follows dependency order and shutdown reverses it. Plugins can use `setup/start/stop/dispose`, config parsers, shared services and async hooks.
+Tracing supports AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers and provider-neutral exporters.
 
-## Cache Platform v2 — BCP 0.2.16+
+## Deployment Platform v2 — BCP 0.2.18+
 
-Use `createCacheStore()` for async cache-aside loading, shared adapters and distributed cache-fill coordination.
+Use `bcp/deployment` to manage production resource lifecycle:
 
 ```ts
 import {
-    createCacheStore,
-} from "bcp/cache";
-
-export const cache =
-    createCacheStore();
-```
+    createDeploymentRuntime,
+} from "bcp/deployment";
 
-```ts
-const user =
-    await cache.getOrSet(
-        "user:42",
-        () => loadUser(42),
-        {
-            ttlMs: 60_000,
-            tags: ["users"],
-            paths: ["/users/42"],
-        }
-    );
+export const deployment =
+    createDeploymentRuntime({
+        serviceName: "bcp-app",
+    });
 ```
 
-For multiple instances, connect a shared cache and lock provider:
+Register dependencies first:
 
 ```ts
-import {
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
+deployment.addResource({
+    name: "database",
 
-const redisCache =
-    createRedisCacheAdapter({
-        client: redisClient,
-    });
+    async start() {
+        await db.connect();
+    },
 
-const redisLock =
-    createRedisCacheLockAdapter({
-        client: redisClient,
-    });
+    ready() {
+        return db.status === "ready";
+    },
 
-export const cache =
-    createCacheStore({
-        adapter: redisCache,
-        lock: redisLock,
-    });
+    async stop() {
+        await db.close();
+    },
+});
 ```
 
-BCP does not install or own a Redis client. The default adapter namespace is `bcp:{cache}`. The original `cache()` and `dedupe()` APIs remain available for backward-compatible process-local caching.
-
-## Observability Platform v3 — BCP 0.2.17+
+Register workers/realtime services afterward so reverse-order shutdown stops them before their shared database/cache/Redis dependencies.
 
-Use the existing `bcp/observability` entrypoint for tracing as well as metrics and health.
+Start runtime:
 
 ```ts
-import {
-    createTracer,
-} from "bcp/observability";
-
-export const tracer =
-    createTracer({
-        serviceName: "my-app",
-    });
+await deployment.start();
 ```
 
-Trace incoming Middleware System v2 requests:
+Readiness endpoint:
 
 ```ts
 import {
-    createRequestTracingMiddleware,
-} from "bcp/observability";
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
 
-export const middleware =
-    createRequestTracingMiddleware(
-        tracer
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
     );
+}
 ```
 
-The middleware continues valid W3C `traceparent` headers, preserves `x-correlation-id`, creates a server span and includes active trace headers in the response.
-
-Create child spans for application work:
+Install graceful signal handling when the app owns process signals:
 
 ```ts
-await tracer.withSpan(
-    "order.checkout",
-    async () => {
-        await tracer.withSpan(
-            "database.order.insert",
-            createOrder,
-            {
-                kind: "client",
-            }
-        );
-    }
-);
+const removeSignals =
+    deployment.installSignalHandlers();
 ```
 
-For jobs, workflows, events and realtime payloads, propagate context explicitly:
+Default signals are `SIGTERM` and `SIGINT`.
 
-```ts
-import {
-    createTraceCarrier,
-    runWithTraceCarrier,
-} from "bcp/observability";
-
-const trace =
-    createTraceCarrier();
+Deployment identity can be supplied through:
 
-await jobs.enqueue(
-    "order.process",
-    {
-        orderId,
-        trace,
-    }
-);
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
 ```
 
-Consumer:
+## Stability baseline — BCP 0.2.19
 
-```ts
-await runWithTraceCarrier(
-    payload.trace,
-    () =>
-        tracer.withSpan(
-            "job order.process",
-            handler,
-            {
-                kind: "consumer",
-            }
-        )
-);
-```
+BCP `0.2.19` freezes the documented `0.2.x` public `bcp/*` entrypoints and prepared package-resolution contract before the next `0.3.0` baseline.
 
-Use `getTraceLogFields()` to attach `traceId`, `spanId` and `correlationId` to structured logs.
+Application code should import documented public entrypoints and avoid private framework `packages/*` paths. This keeps applications compatible with the frozen `0.2.19` surface.
 
-BCP does not install OpenTelemetry or a vendor APM SDK. Production collector integration is application-owned through `TraceSpanExporter`.
+## Production build
 
-## Generate framework files
+```bash
+npm run build
+npm start
+```
+
+## Deployment package
 
 ```bash
-npm run generate -- page dashboard/users
-npm run generate -- api users
-npm run generate -- middleware
-npm run generate -- migration create_users
+npm run package
 ```
 
+BCP excludes project `.env` files and application `devDependencies` from the deployment package. Supply secrets through the deployment environment.
+
+BCP 0.2.19 preserves compiled `.mjs` runtimes for the main server entrypoints, including config, auth, observability, deployment, server and middleware.
+
 ## Direct CLI usage
 
 For PowerShell:
@@ -403,18 +214,3 @@ npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
 npm exec -- bcp-framework package
 ```
-
-## Production build
-
-```bash
-npm run build
-npm start
-```
-
-## Deployment package
-
-```bash
-npm run package
-```
-
-BCP excludes project `.env` files and application `devDependencies` from the deployment package. Supply secrets through the deployment environment.