create-bcp-app 0.2.16 → 0.2.18

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,13 +26,12 @@ 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
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
-npm exec -- bcp-framework generate page dashboard/users
 npm exec -- bcp-framework routes
 npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
@@ -45,8 +42,6 @@ Microsoft SQL Server can install another Windows executable named `bcp.exe`, so
 
 ## Interactive choices
 
-The generator asks for optional application presets:
-
 ```text
 Use Tailwind CSS?
 Select a database:
@@ -69,17 +64,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.2.16` target:
+Example for the `0.2.18` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.16",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.18",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.16"
+    "version": "0.2.18"
   },
   "packageManager": "npm",
   "presets": {
@@ -91,7 +86,7 @@ Example for the `0.2.16` 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
 
@@ -107,88 +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.
-
-## Observability
-
-```ts
-import {
-    createHealthRegistry,
-    createMetricsRegistry,
-} from "bcp/observability";
-```
+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
-            );
-        }
-    );
 ```
 
-`bcp/workflow` supports sequential/parallel steps, retry, persisted delays, compensation and optional execution through `bcp/jobs`.
-
-## Transactional Outbox & Events — 0.2.12+
+Durable Redis-compatible queues/schedules, workflow orchestration and transactional outbox/event delivery are available without forcing a Redis client dependency.
 
-Applications using the SQL Database Platform can persist integration events in the same transaction as business data:
-
-```ts
-await db.transaction(
-    async tx => {
-        await tx.execute(
-            "INSERT INTO orders ..."
-        );
-
-        await outbox.publish(
-            tx,
-            "order.created",
-            {
-                orderId: 42,
-            }
-        );
-    }
-);
-```
-
-After commit, `createOutboxDispatcher()` can hand off events to durable jobs/custom publishers.
-
-## Realtime Platform — 0.2.13+
-
-Generated applications can add server-side realtime channels without changing the scaffold preset model:
+## Realtime
 
 ```ts
 import {
@@ -199,242 +129,138 @@ export const realtime =
     createRealtime();
 ```
 
-Channel/room usage:
-
-```ts
-const connection =
-    await realtime.connect();
-
-await connection.join(
-    "orders:42"
-);
-
-await realtime.broadcast(
-    "orders:42",
-    "order.updated",
-    {
-        status: "paid",
-    }
-);
-```
+BCP does not install a WebSocket server library. Applications adapt their provider to `RealtimeSocket`; SSE is built in.
 
-BCP does not install a WebSocket library. Adapt your selected provider to `RealtimeSocket`. SSE is available directly through `realtime.sse()`.
+## Testing
 
-The memory broker/presence store are local-only. Multi-instance production deployments should provide shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+`bcp/testing` provides request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime test harnesses and does not require Jest or Vitest.
 
-## Testing Platform — 0.2.14+
+## Plugins
 
-`bcp/testing` adds framework-native test helpers without requiring a specific test runner.
+`bcp/plugins` provides dependency ordering, module composition, lifecycle hooks, config parsing, shared services and async hooks.
 
-Request/route example:
+## 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();
 ```
 
-Create a real signed BCP auth session for authenticated requests:
-
-```ts
-import {
-    createTestAuthSession,
-} from "bcp/testing";
-
-const session =
-    await createTestAuthSession(
-        {
-            id: 42,
-            role: "admin",
-        },
-        {
-            secret:
-                process.env.BCP_SESSION_SECRET,
-        }
-    );
-
-app.setCookie(
-    session.cookieName,
-    session.token
-);
-```
+Multi-instance applications can use Redis-compatible cache and lock adapters for distributed cache-fill coordination.
 
-Rollback database tests:
+## Observability Platform v3
 
 ```ts
 import {
-    withTestTransaction,
-} from "bcp/testing";
-
-await withTestTransaction(
-    db,
-    async tx => {
-        await tx.execute(
-            "INSERT INTO users ..."
-        );
-    }
-);
-```
-
-Infrastructure helpers include:
+    createTracer,
+} from "bcp/observability";
 
-```text
-createJobTestHarness()
-createWorkflowTestHarness()
-createOutboxTestHarness()
-createRealtimeTestSocket()
-createRealtimeTestHarness()
-readSseEvents()
-createFakeClock()
-createSequenceIdFactory()
-runTestMiddleware()
+export const tracer =
+    createTracer({
+        serviceName: "my-app",
+    });
 ```
 
-`bcp/testing` is server-only. It can be used with Node `node:test`, Vitest, Jest or another runner; BCP does not install those runners as framework dependencies.
+Tracing supports W3C `traceparent`, correlation IDs, request middleware, explicit carriers for jobs/workflows/events/realtime and provider-neutral exporters.
 
-## Plugin & Module Platform — 0.2.15+
+## Deployment Platform v2 — 0.2.18+
 
-Use `bcp/plugins` to compose reusable server-side application modules with explicit lifecycle and dependencies.
+Use `bcp/deployment` to coordinate application resources in production:
 
 ```ts
 import {
-    createPluginHost,
-    defineModule,
-    definePlugin,
-} from "bcp/plugins";
-
-const databasePlugin =
-    definePlugin({
-        name: "database",
-        setup(context) {
-            context.services.provide(
-                "database",
-                db
-            );
-        },
-    });
+    createDeploymentRuntime,
+} from "bcp/deployment";
 
-const jobsPlugin =
-    definePlugin({
-        name: "jobs",
-        requires: [
-            "database",
-        ],
+export const deployment =
+    createDeploymentRuntime({
+        serviceName: "my-app",
     });
+```
 
-const backendModule =
-    defineModule({
-        name: "backend",
-        plugins: [
-            databasePlugin,
-            jobsPlugin,
-        ],
-    });
+Register shared dependencies before components that use them:
 
-const host =
-    createPluginHost({
-        modules: [
-            backendModule,
-        ],
-    });
+```ts
+deployment.addResource({
+    name: "database",
 
-await host.start();
-```
+    async start() {
+        await db.connect();
+    },
 
-Plugins can use `setup/start/stop/dispose`, typed config parsers, a shared service registry and an awaited in-process hook bus. Required dependencies start first; shutdown runs in reverse order.
+    ready() {
+        return db.status === "ready";
+    },
 
-`bcp/plugins` is server-only and cannot be imported into page/client bundles.
+    async stop() {
+        await db.close();
+    },
+});
 
-## Cache Platform v2 — 0.2.16+
+deployment.addResource({
+    name: "workers",
 
-Use the existing `bcp/cache` entrypoint for provider-neutral shared caching while keeping the original `cache()` and `dedupe()` APIs available.
+    start() {
+        worker = jobs.startWorker();
+    },
 
-```ts
-import {
-    createCacheStore,
-} from "bcp/cache";
+    async stop() {
+        await worker.stop();
+    },
+});
 
-export const cache =
-    createCacheStore();
+await deployment.start();
 ```
 
-Cache-aside loading:
-
-```ts
-const user =
-    await cache.getOrSet(
-        "user:42",
-        () => loadUser(42),
-        {
-            ttlMs: 60_000,
-            tags: ["users"],
-            paths: ["/users/42"],
-        }
-    );
-```
+Startup follows registration order and shutdown reverses it. This naturally stops workers before database/cache/Redis connections.
 
-For multi-instance deployments, applications can supply Redis-compatible cache and lock adapters:
+Readiness endpoint:
 
 ```ts
 import {
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
 
-const redisCache =
-    createRedisCacheAdapter({
-        client: redisClient,
-    });
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
+    );
+}
+```
 
-const redisLock =
-    createRedisCacheLockAdapter({
-        client: redisClient,
-    });
+Runtime identity can use:
 
-export const cache =
-    createCacheStore({
-        adapter: redisCache,
-        lock: redisLock,
-    });
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
 ```
 
-BCP does not install or own the Redis client. Applications remain responsible for credentials, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
+Install graceful signal handling with:
 
-`getOrSet()` provides local singleflight and can use distributed lock leases with heartbeat renewal to reduce cache stampedes across instances.
-
-## Storage providers
+```ts
+const removeSignals =
+    deployment.installSignalHandlers();
+```
 
-Supported presets are Local Server, Amazon S3 and Cloudflare R2. Storage credentials are server-only and must not use `BCP_PUBLIC_*` variables.
+Default signals are `SIGTERM` and `SIGINT`.
 
 ## 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.18` prepared framework packages use compiled ESM runtime files for the main server entrypoints including config, auth, observability, deployment, server and middleware.
 
 ## Project generators
 
@@ -462,5 +288,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.16.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.18.tgz
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "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.
-
-## Transactional Outbox & Events — BCP 0.2.12+
-
-Use `bcp/events` when application data and an integration event must commit atomically in the same SQL transaction.
-
-```ts
-await db.transaction(
-    async tx => {
-        await tx.execute(
-            "INSERT INTO orders ..."
-        );
-
-        await outbox.publish(
-            tx,
-            "order.created",
-            {
-                orderId: 42,
-            }
-        );
-    }
-);
-```
+Durable jobs support leases, heartbeat, stale recovery and DLQ. Workflows support sequential/parallel steps, retries, persisted delays and compensation.
 
-After commit, `createOutboxDispatcher()` can deliver through durable jobs or a custom publisher.
+## Transactional events
 
-## Realtime Platform — BCP 0.2.13+
+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.
 
-Create a server-side realtime hub:
+## Realtime
 
 ```ts
 import {
@@ -144,224 +64,118 @@ 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();
 ```
 
-Authentication tests can create a real signed BCP session:
-
-```ts
-import {
-    createTestAuthSession,
-} from "bcp/testing";
-
-const session =
-    await createTestAuthSession(
-        {
-            id: 42,
-        },
-        {
-            secret:
-                process.env.BCP_SESSION_SECRET,
-        }
-    );
-
-app.setCookie(
-    session.cookieName,
-    session.token
-);
-```
+Use Redis-compatible cache/lock adapters for multi-instance cache-fill coordination when needed.
 
-Database tests can force rollback after assertions:
+## Observability Platform v3
 
 ```ts
 import {
-    withTestTransaction,
-} from "bcp/testing";
-
-await withTestTransaction(
-    db,
-    async tx => {
-        await tx.execute(
-            "INSERT INTO users ..."
-        );
-    }
-);
-```
+    createTracer,
+} from "bcp/observability";
 
-Additional helpers include job/workflow/outbox harnesses, `runTestMiddleware()`, page loader/guard/action helpers, fake clocks and IDs, a fake `RealtimeSocket`, realtime event assertions and `readSseEvents()`.
+export const tracer =
+    createTracer({
+        serviceName: "bcp-app",
+    });
+```
 
-BCP does not require Jest or Vitest; these helpers work with Node `node:test` or another runner.
+Tracing supports AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers and provider-neutral exporters.
 
-## Plugin & Module Platform — BCP 0.2.15+
+## Deployment Platform v2 — BCP 0.2.18+
 
-Use `bcp/plugins` to compose reusable server-only application services with explicit dependencies.
+Use `bcp/deployment` to manage production resource lifecycle:
 
 ```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",
-        ],
-    });
+    createDeploymentRuntime,
+} from "bcp/deployment";
 
-export const plugins =
-    createPluginHost({
-        plugins: [
-            jobsPlugin,
-            databasePlugin,
-        ],
+export const deployment =
+    createDeploymentRuntime({
+        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.
+Register dependencies first:
 
-Use `defineModule()` when a reusable package needs to bundle multiple plugin definitions into one named module.
+```ts
+deployment.addResource({
+    name: "database",
 
-`bcp/plugins` is server-only and cannot be imported from page/client bundles.
+    async start() {
+        await db.connect();
+    },
 
-## Cache Platform v2 — BCP 0.2.16+
+    ready() {
+        return db.status === "ready";
+    },
 
-Use `createCacheStore()` for async cache-aside loading, shared adapters and distributed cache-fill coordination.
+    async stop() {
+        await db.close();
+    },
+});
+```
 
-```ts
-import {
-    createCacheStore,
-} from "bcp/cache";
+Register workers/realtime services afterward so reverse-order shutdown stops them before their shared database/cache/Redis dependencies.
 
-export const cache =
-    createCacheStore();
-```
+Start runtime:
 
 ```ts
-const user =
-    await cache.getOrSet(
-        "user:42",
-        () => loadUser(42),
-        {
-            ttlMs: 60_000,
-            tags: ["users"],
-            paths: ["/users/42"],
-        }
-    );
+await deployment.start();
 ```
 
-For multiple instances, connect a shared cache and lock provider:
+Readiness endpoint:
 
 ```ts
 import {
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
-
-const redisCache =
-    createRedisCacheAdapter({
-        client: redisClient,
-    });
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
 
-const redisLock =
-    createRedisCacheLockAdapter({
-        client: redisClient,
-    });
-
-export const cache =
-    createCacheStore({
-        adapter: redisCache,
-        lock: redisLock,
-    });
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
+    );
+}
 ```
 
-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.
-
-## Generate framework files
+Install graceful signal handling when the app owns process signals:
 
-```bash
-npm run generate -- page dashboard/users
-npm run generate -- api users
-npm run generate -- middleware
-npm run generate -- migration create_users
+```ts
+const removeSignals =
+    deployment.installSignalHandlers();
 ```
 
-## Direct CLI usage
+Default signals are `SIGTERM` and `SIGINT`.
 
-For PowerShell:
+Deployment identity can be supplied through:
 
-```powershell
-npm exec -- bcp-framework --version
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect
-npm exec -- bcp-framework routes
-npm exec -- bcp-framework dev
-npm exec -- bcp-framework build
-npm exec -- bcp-framework package
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
 ```
 
 ## Production build
@@ -378,3 +192,19 @@ npm run package
 ```
 
 BCP excludes project `.env` files and application `devDependencies` from the deployment package. Supply secrets through the deployment environment.
+
+BCP 0.2.18 prepared framework packages use compiled `.mjs` runtimes for the main server entrypoints, including config, auth, observability, deployment, server and middleware.
+
+## Direct CLI usage
+
+For PowerShell:
+
+```powershell
+npm exec -- bcp-framework --version
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
+npm exec -- bcp-framework package
+```