@chidchanun/bcp 0.2.14 → 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, framework-native testing, 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.14 — Testing Platform`
+> **Development target:** `0.2.15 — Plugin & Module Platform`
 >
-> `0.2.14` 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,7 +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/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test harnesses |
+| 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 |
@@ -75,6 +76,7 @@ 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";
 ```
 
@@ -369,6 +371,81 @@ 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
 
 ```text
@@ -385,6 +462,7 @@ bcp/workflow
 bcp/events
 bcp/realtime
 bcp/testing
+bcp/plugins
 bcp/observability
 bcp/server
 bcp/server-only
@@ -433,7 +511,7 @@ Browser / API / Realtime clients
               |
       security + auth
               |
-       application APIs
+          Plugin Host
        /      |       \
  database  workflows  realtime
     |          |         ^
@@ -469,7 +547,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.14`:
+Before publishing `0.2.15`:
 
 ```bash
 npm run typecheck
@@ -480,7 +558,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.14` adds unit and prepared-package smoke coverage for request/route handling, cookies, signed auth sessions, rollback transactions, middleware execution, jobs, workflows, outbox delivery, realtime sockets, SSE parsing, 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.
 
@@ -509,12 +587,13 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `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.14` establishes framework-native testing for the current BCP application/runtime stack without coupling the framework to a specific test runner.
+`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.15 — Plugin & Module Platform`**, focused on reusable framework modules, lifecycle hooks, configuration extension, package metadata and plugin discovery/registration while keeping the current public entrypoints stable.
+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.14 — Testing Platform`
+> **Documentation target:** BCP Framework `0.2.15 — Plugin & Module Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -40,63 +40,56 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.12` | Transactional Outbox & Events |
 | `0.2.13` | Realtime Platform |
 | `0.2.14` | Testing Platform |
+| `0.2.15` | Plugin & Module Platform |
 
-## 0.2.14 — Testing Platform
+## 0.2.15 — Plugin & Module Platform
 
-`0.2.14` adds the server-only `bcp/testing` public entrypoint.
+`0.2.15` adds the server-only `bcp/plugins` public entrypoint.
 
 Primary APIs:
 
 ```ts
 import {
-    createFakeClock,
-    createJobTestHarness,
-    createOutboxTestHarness,
-    createRealtimeTestHarness,
-    createRealtimeTestSocket,
-    createRouteTestHandler,
-    createSequenceIdFactory,
-    createTestApp,
-    createTestAuthSession,
-    createWorkflowTestHarness,
-    expectResponse,
-    readSseEvents,
-    runTestMiddleware,
-    withTestTransaction,
-} from "bcp/testing";
+    createPluginHookBus,
+    createPluginHost,
+    createPluginServiceRegistry,
+    defineModule,
+    definePlugin,
+} from "bcp/plugins";
 ```
 
-Testing model:
+Runtime model:
 
 ```text
-node:test / Vitest / Jest / other runner
-                |
-                v
-            bcp/testing
-                |
-     +----------+-----------+
-     |          |           |
- Request     Database   Infrastructure
- Route       rollback   jobs/workflow
- Response      tx       outbox/realtime
- Auth                    SSE/socket
- Middleware
+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 helpers use existing BCP runtime contracts rather than defining a parallel mock framework. Signed auth sessions use the production session token implementation; middleware tests execute the real onion pipeline; job/workflow/outbox/realtime harnesses wrap their actual platform APIs.
+Startup follows topological dependency order. Stop/dispose runs in reverse order. A failed startup rolls back plugins that already started.
 
-BCP does not add a Jest or Vitest dependency.
+Modules are named bundles of plugins; they do not create a separate lifecycle graph.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `testing-platform.md` | Request, auth, database, middleware, jobs, workflow, outbox, realtime and SSE testing |
-| `api-reference.md` | `bcp/testing` public APIs |
-| `platform-manifest.json` | Testing capability flags and public entrypoint |
-| `api-manifest.json` | `bcp/testing` source/guide ownership |
-| `docs-web-manifest.json` | Testing docs navigation and `0.2.14` release route |
-| `releases/0.2.14.md` | Testing 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
 
@@ -123,8 +116,9 @@ When framework behavior or public surface changes:
 | `/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.14` | `releases/0.2.14.md` |
+| `/releases/0.2.15` | `releases/0.2.15.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -144,6 +138,7 @@ bcp/workflow
 bcp/events
 bcp/realtime
 bcp/testing
+bcp/plugins
 bcp/observability
 bcp/server
 bcp/server-only
@@ -154,7 +149,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.14`:
+Before publishing `0.2.15`:
 
 ```bash
 npm run typecheck
@@ -165,6 +160,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Testing Platform validation covers request/route behavior, cookie persistence, signed auth sessions, rollback transactions, middleware execution, deterministic clocks/IDs, job/workflow/outbox/realtime harnesses, SSE parsing, server-only boundaries, compiled `testing.mjs` 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.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -106,9 +106,17 @@
       "source": "packages/client/src/testing.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-testing",
-      "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
+      "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, page/server execution, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
       "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform"]
     },
+    {
+      "package": "bcp/plugins",
+      "source": "packages/client/src/plugins.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-plugins",
+      "summary": "Plugin and module composition with dependency ordering, lifecycle hooks, typed config parsing, shared services and asynchronous extension hooks.",
+      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability"]
+    },
     {
       "package": "bcp/observability",
       "source": "packages/client/src/observability.ts",

package/docs/api-reference.md

@@ -308,6 +308,52 @@ The package is server-only; the client boundary validator rejects `bcp/testing`
 
 Related guides: [Testing Platform](testing-platform.md), [Authentication](authentication.md), [Database](database.md), [Durable Jobs](durable-jobs.md), [Workflow Orchestration](workflow-orchestration.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md).
 
+## `bcp/plugins`
+
+Server-only Plugin & Module Platform APIs added in `0.2.15`.
+
+```ts
+import {
+    createPluginHookBus,
+    createPluginHost,
+    createPluginServiceRegistry,
+    defineModule,
+    definePlugin,
+    PluginDependencyError,
+    PluginLifecycleError,
+    type PluginConfigParser,
+    type PluginConfigSchema,
+    type PluginContext,
+    type PluginDefinition,
+    type PluginHookBus,
+    type PluginHookHandler,
+    type PluginHost,
+    type PluginHostOptions,
+    type PluginHostView,
+    type PluginModule,
+    type PluginRecord,
+    type PluginServiceKey,
+    type PluginServiceRegistry,
+    type PluginState,
+} from "bcp/plugins";
+```
+
+`createPluginHost()` resolves required and optional plugin dependencies and starts plugins in topological order. `stop()` and `close()` shut them down/dispose them in reverse dependency order.
+
+`defineModule()` groups reusable plugin definitions while preserving one global host dependency graph.
+
+Plugin configuration can be parsed with a schema/parser during setup. Values from `PluginHostOptions.configs` override plugin-local defaults before parsing.
+
+`PluginServiceRegistry` provides shared string/Symbol-keyed services. `PluginHookBus` provides awaited, in-process extension hooks in registration order.
+
+Missing dependencies and dependency cycles throw `PluginDependencyError`. Setup/start failures surface `PluginLifecycleError`; startup failures roll back plugins that already started in the current transition.
+
+`host.plugin()` and `host.plugins()` expose inspectable lifecycle records.
+
+`bcp/plugins` is server-only and is rejected from page/client bundles.
+
+Related guides: [Plugin & Module Platform](plugin-module-platform.md), [Configuration](configuration.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+
 ## `bcp/observability`
 
 Server-only Observability Platform v2 APIs for process-local counters, gauges, histograms, Prometheus exposition, request metrics middleware and health/readiness checks.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.14",
+  "versionTarget": "0.2.15",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -88,11 +88,12 @@
     {
       "id": "developer-experience",
       "title": "Developer Experience",
-      "description": "Project generators, diagnostics, testing, project metadata and framework maintenance tooling.",
+      "description": "Project generators, diagnostics, testing, plugin composition, project metadata and framework maintenance tooling.",
       "pages": [
         { "route": "/docs/generators", "source": "generators.md", "title": "Project Generators" },
         { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" },
-        { "route": "/docs/testing-platform", "source": "testing-platform.md", "title": "Testing Platform" }
+        { "route": "/docs/testing-platform", "source": "testing-platform.md", "title": "Testing Platform" },
+        { "route": "/docs/plugin-module-platform", "source": "plugin-module-platform.md", "title": "Plugin & Module Platform" }
       ]
     },
     {
@@ -115,7 +116,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.14", "source": "releases/0.2.14.md", "version": "0.2.14", "state": "unreleased" },
+    { "route": "/releases/0.2.15", "source": "releases/0.2.15.md", "version": "0.2.15", "state": "unreleased" },
+    { "route": "/releases/0.2.14", "source": "releases/0.2.14.md", "version": "0.2.14" },
     { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13" },
     { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12" },
     { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "releaseState": "unreleased",
-  "baseline": "testing-platform",
+  "baseline": "plugin-module-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -24,6 +24,7 @@
     "bcp/events",
     "bcp/realtime",
     "bcp/testing",
+    "bcp/plugins",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -138,6 +139,15 @@
     "testRealtimeSocket": true,
     "testSseReader": true,
     "deterministicTestClock": true,
+    "pluginModulePlatform": true,
+    "pluginDefinitions": true,
+    "pluginModules": true,
+    "pluginDependencyOrdering": true,
+    "pluginLifecycleHooks": true,
+    "pluginConfigSchemas": true,
+    "pluginServiceRegistry": true,
+    "pluginHookBus": true,
+    "pluginLifecycleRollback": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -177,7 +187,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.13",
+    "previousBaseline": "0.2.14",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -201,7 +211,8 @@
     "transactionalOutboxEvents": "transactional-outbox-events.md",
     "realtimePlatform": "realtime-platform.md",
     "testingPlatform": "testing-platform.md",
+    "pluginModulePlatform": "plugin-module-platform.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.14.md"
+    "releaseNotes": "releases/0.2.15.md"
   }
 }