@chidchanun/bcp 0.2.13 → 0.2.15

package/README.md

@@ -1,10 +1,10 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, observability, uploads, storage and standalone Node.js deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, framework-native testing, plugin/module composition, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.13 — Realtime Platform`
+> **Development target:** `0.2.15 — Plugin & Module Platform`
 >
-> `0.2.13` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.15` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
@@ -25,6 +25,8 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases |
 | Events | Transactional outbox, SQL persistence, dispatcher leases, retries, event bus and durable queue handoff |
 | Realtime | Channels/rooms, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
+| Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test harnesses |
+| Plugins & modules | Dependency ordering, lifecycle hooks, config parsing, service registry and async extension hooks |
 | Observability | Structured logs, metrics, Prometheus output and health/readiness checks |
 | Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
 | Caching | Response cache and revalidation primitives |
@@ -73,6 +75,8 @@ import { createJobQueue } from "bcp/jobs";
 import { createWorkflow } from "bcp/workflow";
 import { createTransactionalOutbox } from "bcp/events";
 import { createRealtime } from "bcp/realtime";
+import { createTestApp } from "bcp/testing";
+import { createPluginHost } from "bcp/plugins";
 import { createMetricsRegistry } from "bcp/observability";
 ```
 
@@ -165,10 +169,6 @@ Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
 
 ## Realtime Platform — 0.2.13
 
-`0.2.13` adds the server-only `bcp/realtime` public entrypoint.
-
-Create a hub:
-
 ```ts
 import {
     createRealtime,
@@ -178,7 +178,7 @@ export const realtime =
     createRealtime();
 ```
 
-### Channels / rooms
+Join a channel and broadcast:
 
 ```ts
 const connection =
@@ -197,135 +197,254 @@ await realtime.broadcast(
 );
 ```
 
-Rooms are represented by channel names. Connections receive broadcasts only for channels they joined.
+BCP intentionally does not install a WebSocket server library. Applications adapt `ws`, uWebSockets.js or another transport to `RealtimeSocket`. SSE is built in through Web `Response`.
+
+Read more: [Realtime Platform](docs/realtime-platform.md)
+
+## Testing Platform — 0.2.14
+
+`0.2.14` adds the server-only `bcp/testing` entrypoint. It is test-runner neutral and does not add Jest or Vitest as framework dependencies.
 
-### Presence
+### Request and route tests
 
 ```ts
-await connection.join(
-    "project:7",
-    {
-        presence: {
-            status: "online",
+import {
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+} from "bcp/testing";
+
+const handler =
+    createRouteTestHandler({
+        GET() {
+            return {
+                ok: true,
+            };
         },
-    }
-);
-
-const members =
-    await realtime.members(
-        "project:7"
-    );
-```
+    });
 
-The built-in memory presence store is process-local. Multi-instance deployments should provide a shared `RealtimePresenceStore`.
+const app =
+    createTestApp({
+        handler,
+    });
 
-### Authentication and private channels
+const response =
+    await app.get(
+        "/api/health"
+    );
 
-```ts
-const realtime =
-    createRealtime({
-        authenticate:
-            async ({ request }) =>
-                request
-                    ? loadRealtimeUser(
-                        request
-                    )
-                    : null,
-
-        getUserId:
-            user => user.id,
-
-        authorizeChannel:
-            ({ connection, channel }) =>
-                !channel.startsWith(
-                    "private:"
-                ) ||
-                Boolean(
-                    connection.user
-                ),
+await expectResponse(response)
+    .status(200)
+    .json({
+        ok: true,
     });
 ```
 
-### WebSocket provider contract
+`createTestApp()` keeps an in-memory cookie jar, supports default headers and can send JSON bodies directly.
 
-BCP intentionally does not install `ws`, Socket.IO or another WebSocket server dependency.
+### Authentication tests
 
-Adapt the selected server/provider to `RealtimeSocket`, then attach it:
+Create a real signed BCP session token instead of a fake test-only user header:
 
 ```ts
-const connection =
-    await realtime.attachSocket(
-        socketAdapter,
+import {
+    createTestAuthSession,
+} from "bcp/testing";
+
+const session =
+    await createTestAuthSession(
         {
-            request,
+            id: 42,
+            role: "admin",
+        },
+        {
+            secret:
+                process.env.BCP_SESSION_SECRET,
+            store:
+                authSessionStore,
         }
     );
-```
 
-The JSON socket protocol supports `join`, `leave`, `event` and `ping` messages.
+app.setCookie(
+    session.cookieName,
+    session.token
+);
+```
 
-### Server-Sent Events
+When `store` is provided, the matching server-side auth session record is inserted as well.
 
-SSE is built in through Web `Response`:
+### Rollback database tests
 
 ```ts
-export function GET(
-    request: Request
-) {
-    return realtime.sse(
-        "workflow:42",
-        {
-            signal:
-                request.signal,
-        }
-    );
-}
+import {
+    withTestTransaction,
+} from "bcp/testing";
+
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+
+        // assertions run here
+    }
+);
 ```
 
-### Cross-instance delivery
+The callback uses the real BCP transaction and is deliberately rolled back after the test callback succeeds.
 
-`RealtimeBroker` is the provider-neutral pub/sub boundary. The built-in memory broker supports same-process hubs; production applications can implement shared Redis/NATS/etc. brokers without changing hub APIs.
+### Infrastructure harnesses
 
-```text
-Browser A -> App A ----\
-                       Shared Broker
-Browser B -> App B ----/
-          |             |
-          +---- Shared Presence Store
+```ts
+import {
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createWorkflowTestHarness,
+} from "bcp/testing";
 ```
 
-### Heartbeat
+These harnesses use the real platform contracts rather than separate mock implementations.
+
+Background jobs:
 
 ```ts
-const heartbeat =
-    realtime.startHeartbeat({
-        intervalMs: 20_000,
-    });
+const jobTest =
+    createJobTestHarness(
+        jobs
+    );
+
+await jobTest.drain();
 
-// shutdown
-await heartbeat.stop();
-await realtime.close();
+await jobTest.expectCount(
+    1,
+    {
+        name: "email.welcome",
+        state: "succeeded",
+    }
+);
 ```
 
-`realtime.ping` / `realtime.pong` and `sweepStale()` provide connection liveness cleanup.
+Realtime:
 
-### Jobs / workflows / events integration
+```ts
+const realtimeTest =
+    createRealtimeTestHarness(
+        realtime
+    );
 
-Realtime is the transient delivery edge for durable backend state:
+const {
+    socket,
+    connection,
+} =
+    await realtimeTest.connect();
+
+await connection.join(
+    "orders:42"
+);
 
-```ts
 await realtime.broadcast(
-    `jobs:${job.id}`,
-    "job.progress",
+    "orders:42",
+    "order.updated",
     {
-        progress: 60,
+        status: "paid",
     }
 );
+
+realtimeTest.expectEvent(
+    socket,
+    "order.updated",
+    "orders:42"
+);
 ```
 
-Important business facts should remain in database/outbox/jobs/workflows. Realtime delivery is transient, so reconnecting clients should refetch durable state/history when catch-up is required.
+Other testing primitives include:
 
-Read more: [Realtime Platform](docs/realtime-platform.md)
+```text
+createFakeClock()
+createSequenceIdFactory()
+runTestMiddleware()
+createRealtimeTestSocket()
+readSseEvents()
+```
+
+Read more: [Testing Platform](docs/testing-platform.md)
+
+## Plugin & Module Platform — 0.2.15
+
+`0.2.15` adds the server-only `bcp/plugins` entrypoint for reusable application/framework extensions.
+
+Define plugins with explicit dependencies:
+
+```ts
+import {
+    createPluginHost,
+    definePlugin,
+} from "bcp/plugins";
+
+const databasePlugin =
+    definePlugin({
+        name: "database",
+        setup(context) {
+            context.services.provide(
+                "database",
+                db
+            );
+        },
+        start() {
+            return db.connect();
+        },
+        stop() {
+            return db.disconnect();
+        },
+    });
+
+const jobsPlugin =
+    definePlugin({
+        name: "jobs",
+        requires: [
+            "database",
+        ],
+    });
+
+const host =
+    createPluginHost({
+        plugins: [
+            jobsPlugin,
+            databasePlugin,
+        ],
+    });
+
+await host.start();
+```
+
+Dependency order is resolved automatically. Startup follows dependency order while stop/dispose runs in reverse order.
+
+Modules group reusable plugin sets:
+
+```ts
+import {
+    defineModule,
+} from "bcp/plugins";
+
+const backendModule =
+    defineModule({
+        name: "backend",
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+        ],
+    });
+```
+
+Plugin configuration can be parsed at setup time and overridden through `createPluginHost({ configs })`.
+
+Plugins share a service registry and awaited in-process hook bus through `context.services` and `context.hooks`.
+
+If startup fails, already-started plugins are stopped in reverse order before the lifecycle error is propagated.
+
+Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
 
 ## Public entrypoints
 
@@ -342,6 +461,8 @@ bcp/jobs
 bcp/workflow
 bcp/events
 bcp/realtime
+bcp/testing
+bcp/plugins
 bcp/observability
 bcp/server
 bcp/server-only
@@ -390,13 +511,15 @@ Browser / API / Realtime clients
               |
       security + auth
               |
-       application APIs
+          Plugin Host
        /      |       \
  database  workflows  realtime
     |          |         ^
  outbox       jobs       |
     \__________|_________/
            durable state
+
+Testing Platform exercises these server contracts without becoming part of browser runtime.
 ```
 
 ## Packaging
@@ -424,7 +547,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.13`:
+Before publishing `0.2.15`:
 
 ```bash
 npm run typecheck
@@ -435,7 +558,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.13` adds unit and prepared-package smoke coverage for broker broadcasts, channel membership, presence, authentication/channel authorization, socket protocol, heartbeat cleanup, SSE streaming, public runtime compilation and browser boundary enforcement.
+`0.2.15` adds unit and prepared-package smoke coverage for plugin dependency ordering, missing/cyclic dependencies, modules, config parsing, shared services, async hooks, lifecycle rollback, compiled `plugins.mjs` execution and browser boundary enforcement.
 
 Do not tag or publish until the exact final release commit passes the full RC sequence.
 
@@ -463,12 +586,14 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.11` | Workflow Orchestration |
 | `0.2.12` | Transactional Outbox & Events |
 | `0.2.13` | Realtime Platform |
+| `0.2.14` | Testing Platform |
+| `0.2.15` | Plugin & Module Platform |
 
 ## Roadmap
 
-`0.2.13` establishes provider-neutral live delivery on top of the durable database/outbox/jobs/workflow stack.
+`0.2.15` establishes reusable server-side extension composition while keeping BCP subsystem contracts provider-neutral and independently testable.
 
-The next logical milestone is **`0.2.14 — Testing Platform`**, focused on framework-native request/route/auth/database/jobs/workflow/realtime testing utilities and application test harnesses.
+The next logical milestone is **`0.2.16 — Cache Platform v2`**, focused on distributed cache adapters, Redis-compatible caching, locking, stampede protection and production cache observability.
 
 Native desktop/mobile compilation remains later roadmap work.
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.13 — Realtime Platform`
+> **Documentation target:** BCP Framework `0.2.15 — Plugin & Module Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -39,56 +39,57 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.11` | Workflow Orchestration |
 | `0.2.12` | Transactional Outbox & Events |
 | `0.2.13` | Realtime Platform |
+| `0.2.14` | Testing Platform |
+| `0.2.15` | Plugin & Module Platform |
 
-## 0.2.13 — Realtime Platform
+## 0.2.15 — Plugin & Module Platform
 
-`0.2.13` adds the server-only `bcp/realtime` public entrypoint.
+`0.2.15` adds the server-only `bcp/plugins` public entrypoint.
 
 Primary APIs:
 
 ```ts
 import {
-    createMemoryRealtimeBroker,
-    createMemoryRealtimePresenceStore,
-    createRealtime,
-    createRealtimeSseResponse,
-} from "bcp/realtime";
+    createPluginHookBus,
+    createPluginHost,
+    createPluginServiceRegistry,
+    defineModule,
+    definePlugin,
+} from "bcp/plugins";
 ```
 
 Runtime model:
 
 ```text
-client connection
-      |
-      v
-RealtimeHub
-      |
-      +-- channels / rooms
-      +-- auth / channel authorization
-      +-- presence
-      +-- heartbeat
-      |
-      +-- RealtimeBroker
-      |       -> cross-hub delivery
-      |
-      +-- RealtimeSocket
-      |       -> WebSocket provider adapter
-      |
-      +-- SSE Response
+Plugin Host
+   |
+   +-- dependency graph
+   |      -> required / optional dependencies
+   |
+   +-- lifecycle
+   |      -> setup -> start -> stop -> dispose
+   |
+   +-- service registry
+   |      -> typed shared application services
+   |
+   +-- async hook bus
+          -> in-process extension points
 ```
 
-The memory broker/presence store are process-local. Multi-instance deployments should provide shared implementations.
+Startup follows topological dependency order. Stop/dispose runs in reverse order. A failed startup rolls back plugins that already started.
+
+Modules are named bundles of plugins; they do not create a separate lifecycle graph.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `realtime-platform.md` | Channels, presence, WebSocket adapter, SSE, heartbeat and broker model |
-| `api-reference.md` | `bcp/realtime` public APIs |
-| `platform-manifest.json` | Realtime capability flags and public entrypoint |
-| `api-manifest.json` | `bcp/realtime` source/guide ownership |
-| `docs-web-manifest.json` | Realtime docs navigation and `0.2.13` release route |
-| `releases/0.2.13.md` | Realtime Platform release notes |
+| `plugin-module-platform.md` | Plugin definitions, modules, dependency order, lifecycle, config, services and hooks |
+| `api-reference.md` | `bcp/plugins` public APIs |
+| `platform-manifest.json` | Plugin capability flags and public entrypoint |
+| `api-manifest.json` | `bcp/plugins` source/guide ownership |
+| `docs-web-manifest.json` | Plugin docs navigation and `0.2.15` release route |
+| `releases/0.2.15.md` | Plugin & Module Platform release notes |
 
 ## Update rule
 
@@ -114,8 +115,10 @@ When framework behavior or public surface changes:
 | `/docs/workflow-orchestration` | `workflow-orchestration.md` |
 | `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
 | `/docs/realtime-platform` | `realtime-platform.md` |
+| `/docs/testing-platform` | `testing-platform.md` |
+| `/docs/plugin-module-platform` | `plugin-module-platform.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.13` | `releases/0.2.13.md` |
+| `/releases/0.2.15` | `releases/0.2.15.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -134,6 +137,8 @@ bcp/jobs
 bcp/workflow
 bcp/events
 bcp/realtime
+bcp/testing
+bcp/plugins
 bcp/observability
 bcp/server
 bcp/server-only
@@ -144,7 +149,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.13`:
+Before publishing `0.2.15`:
 
 ```bash
 npm run typecheck
@@ -155,6 +160,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Realtime validation covers broker broadcasts, presence, authentication/channel authorization, socket protocol, heartbeat cleanup, SSE streaming, server-only boundaries, compiled `realtime.mjs` package execution and docs/platform/API parity.
+Plugin Platform validation covers dependency ordering, missing/cyclic dependencies, module composition, typed config parsing, service sharing, async hooks, reverse shutdown, startup rollback, server-only boundaries, compiled `plugins.mjs` package execution and docs/platform/API parity.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.