@chidchanun/bcp 0.2.13 → 0.2.15

package/docs/plugin-module-platform.md

@@ -0,0 +1,391 @@
+# Plugin & Module Platform
+
+BCP `0.2.15` adds the server-only `bcp/plugins` entrypoint for composing framework/application extensions with explicit dependencies and lifecycle control.
+
+## Import
+
+```ts
+import {
+    createPluginHost,
+    defineModule,
+    definePlugin,
+} from "bcp/plugins";
+```
+
+`bcp/plugins` is server-only and cannot be imported from page/client bundles.
+
+## Define a plugin
+
+```ts
+export const databasePlugin =
+    definePlugin({
+        name: "database",
+
+        async setup(context) {
+            context.services.provide(
+                "database",
+                db
+            );
+        },
+
+        async start() {
+            await db.connect();
+        },
+
+        async stop() {
+            await db.disconnect();
+        },
+    });
+```
+
+A plugin can expose four lifecycle hooks:
+
+```text
+setup()
+start()
+stop()
+dispose()
+```
+
+`setup()` prepares dependency wiring and shared services. `start()` begins runtime work. `stop()` shuts active work down. `dispose()` releases setup-level resources when the host closes.
+
+## Dependency ordering
+
+```ts
+const jobsPlugin =
+    definePlugin({
+        name: "jobs",
+        requires: [
+            "database",
+        ],
+    });
+```
+
+The host resolves required dependencies before dependents:
+
+```text
+database
+   ↓
+jobs
+   ↓
+workflow
+```
+
+Startup follows this order. Shutdown and disposal run in reverse order.
+
+Missing required dependencies throw `PluginDependencyError` before lifecycle execution begins.
+
+Dependency cycles are rejected:
+
+```text
+a -> b -> c -> a
+```
+
+Optional dependencies participate in ordering only when they are registered:
+
+```ts
+definePlugin({
+    name: "metrics-addon",
+    optional: [
+        "observability",
+    ],
+});
+```
+
+## Create a host
+
+```ts
+const host =
+    createPluginHost({
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+        ],
+    });
+
+await host.start();
+```
+
+For graceful shutdown:
+
+```ts
+await host.stop();
+await host.close();
+```
+
+`close()` is idempotent. If the host is still started it stops the runtime before disposal.
+
+## Modules
+
+A module is a named bundle of plugin definitions.
+
+```ts
+export const backendModule =
+    defineModule({
+        name: "backend",
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+            workflowPlugin,
+        ],
+    });
+
+const host =
+    createPluginHost({
+        modules: [
+            backendModule,
+        ],
+    });
+```
+
+Modules do not create a second lifecycle system. They only group plugins; dependency resolution still occurs globally across the host.
+
+You can also register before setup begins:
+
+```ts
+host.use(databasePlugin);
+host.use(backendModule);
+```
+
+Registration is locked after setup starts so runtime dependency graphs cannot change underneath active plugins.
+
+## Typed plugin configuration
+
+A plugin can parse its own configuration:
+
+```ts
+const httpPlugin =
+    definePlugin<{
+        port: number;
+    }>({
+        name: "http",
+
+        config: {
+            port: 3000,
+        },
+
+        schema: {
+            parse(value) {
+                const port =
+                    Number(
+                        (
+                            value as {
+                                port?: unknown;
+                            }
+                        )?.port
+                    );
+
+                if (!Number.isInteger(port)) {
+                    throw new Error(
+                        "port must be an integer"
+                    );
+                }
+
+                return {
+                    port,
+                };
+            },
+        },
+
+        setup(context) {
+            console.log(
+                context.config.port
+            );
+        },
+    });
+```
+
+Application-level host configuration overrides the plugin default:
+
+```ts
+const host =
+    createPluginHost({
+        plugins: [
+            httpPlugin,
+        ],
+        configs: {
+            http: {
+                port: 8080,
+            },
+        },
+    });
+```
+
+A schema may be an object with `parse()` or a parser function.
+
+## Shared service registry
+
+Plugins can publish typed application services:
+
+```ts
+setup(context) {
+    context.services.provide(
+        "mailer",
+        mailer
+    );
+}
+```
+
+A dependent plugin can consume the service:
+
+```ts
+setup(context) {
+    const mailer =
+        context.services.get<Mailer>(
+            "mailer"
+        );
+}
+```
+
+Available operations:
+
+```text
+provide()
+get()
+optional()
+has()
+delete()
+keys()
+```
+
+Duplicate `provide()` calls are rejected unless `{ replace: true }` is explicit.
+
+String and Symbol service keys are supported.
+
+## Asynchronous extension hooks
+
+The host also exposes a small asynchronous hook bus:
+
+```ts
+const unsubscribe =
+    context.hooks.on<{
+        userId: number;
+    }>(
+        "user.created",
+        async event => {
+            await sendWelcomeEmail(
+                event.userId
+            );
+        }
+    );
+```
+
+Emit from another plugin:
+
+```ts
+await context.hooks.emit(
+    "user.created",
+    {
+        userId: 42,
+    }
+);
+```
+
+Handlers run in registration order and are awaited. The hook bus is intended for in-process extension points, not durable event delivery.
+
+Use `bcp/events` for durable integration events that must survive process failure.
+
+## Lifecycle failure behavior
+
+If a plugin fails during `start()`, plugins that already started in that transition are stopped in reverse order before `PluginLifecycleError` is propagated.
+
+```text
+database start ✅
+jobs start ✅
+workflow start ❌
+
+rollback:
+jobs stop
+database stop
+```
+
+This prevents partially-started application runtimes from being left active after a startup failure.
+
+Lifecycle records can be inspected:
+
+```ts
+host.plugin("jobs");
+host.plugins();
+```
+
+States include:
+
+```text
+registered
+setting-up
+ready
+starting
+started
+stopping
+stopped
+failed
+```
+
+## Relationship to existing BCP platforms
+
+`bcp/plugins` composes services; it does not replace their own durability/lifecycle contracts.
+
+```text
+Plugin Host
+   |
+   +-- Database plugin ------> bcp/database
+   +-- Jobs plugin ----------> bcp/jobs
+   +-- Workflow plugin ------> bcp/workflow
+   +-- Events plugin --------> bcp/events
+   +-- Realtime plugin ------> bcp/realtime
+   +-- Observability plugin -> bcp/observability
+```
+
+A plugin can wrap any existing BCP subsystem and expose the resulting instance through the service registry.
+
+## Production guidance
+
+Keep plugin names stable because dependency declarations reference names.
+
+Prefer explicit required dependencies instead of relying on registration order.
+
+Use plugin configuration parsing near the plugin boundary so invalid configuration fails before startup.
+
+Use `dispose()` for resources created during setup, and `stop()` for active runtime processes such as workers, schedulers and network listeners.
+
+Do not use the hook bus as a durable message broker. Use Transactional Outbox/Jobs for delivery guarantees.
+
+## 0.2.15 scope
+
+Included:
+
+```text
+bcp/plugins
+definePlugin()
+defineModule()
+createPluginHost()
+required dependencies
+optional dependencies
+topological ordering
+cycle detection
+setup/start/stop/dispose lifecycle
+reverse shutdown
+startup rollback
+plugin state records
+config parser/schema contract
+host config overrides
+service registry
+async hook bus
+server-only boundary
+compiled plugins.mjs
+unit tests
+prepared package smoke
+```
+
+Not included yet:
+
+```text
+automatic npm plugin discovery
+remote plugin loading
+sandboxed/untrusted plugins
+hot plugin replacement
+plugin marketplace
+CLI plugin install command
+```
+
+Those can be added later without changing the core host contract.

package/docs/releases/0.2.14.md

@@ -0,0 +1,241 @@
+# BCP Framework 0.2.14 — Testing Platform
+
+**Release state:** unreleased
+
+BCP `0.2.14` adds framework-native server-side testing utilities through the new `bcp/testing` entrypoint.
+
+The milestone is intentionally test-runner neutral: BCP does not add Jest or Vitest as runtime dependencies. The framework's own suite continues to use Node's built-in `node:test`.
+
+## Highlights
+
+- new server-only `bcp/testing` entrypoint,
+- Request -> Response application test harness,
+- persistent test cookie jar and default headers,
+- API route module testing for GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS,
+- page guard testing through the production guard executor,
+- page loader testing through the production loader executor,
+- form action testing through the production action executor,
+- `FormData` construction helper,
+- lightweight response assertions,
+- real signed BCP auth session generation,
+- optional `AuthSessionStore` registration,
+- rollback-only database test transactions,
+- real Middleware System v2 pipeline execution,
+- deterministic fake clock,
+- deterministic sequence ID factory,
+- background job queue drain/count helpers,
+- workflow execution/state helpers,
+- transactional outbox dispatch/state helpers,
+- in-memory `RealtimeSocket` test adapter,
+- realtime connection/event harness,
+- Server-Sent Events reader,
+- prepared package compilation to `testing.mjs`,
+- package smoke and client-boundary validation.
+
+## Public API
+
+```ts
+import {
+    createFakeClock,
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createRealtimeTestSocket,
+    createRouteTestHandler,
+    createSequenceIdFactory,
+    createTestApp,
+    createTestAuthSession,
+    createTestFormData,
+    createWorkflowTestHarness,
+    expectResponse,
+    readSseEvents,
+    runTestMiddleware,
+    runTestPageAction,
+    runTestPageGuards,
+    runTestPageLoader,
+    withTestTransaction,
+} from "bcp/testing";
+```
+
+## Request and route testing
+
+```ts
+const app =
+    createTestApp({
+        handler:
+            createRouteTestHandler({
+                GET() {
+                    return {
+                        ok: true,
+                    };
+                },
+            }),
+    });
+
+const response =
+    await app.get(
+        "/api/health"
+    );
+
+await expectResponse(response)
+    .status(200)
+    .json({
+        ok: true,
+    });
+```
+
+The harness maintains cookies returned by `Set-Cookie` and sends them on future requests.
+
+## Page server runtime testing
+
+Page loader, guard and form action helpers invoke the same execution functions used by BCP runtime:
+
+```ts
+await runTestPageGuards(
+    guard,
+    {
+        params: {
+            id: "42",
+        },
+    }
+);
+
+await runTestPageLoader(
+    loader,
+    {
+        url:
+            "/users/42?tab=profile",
+    }
+);
+
+await runTestPageAction(
+    updateUser,
+    {
+        actionName:
+            "updateUser",
+        method: "PATCH",
+        fields: {
+            name: "BCP",
+        },
+    }
+);
+```
+
+This preserves guard-data chaining, loader/action Response short-circuits, action method validation and JSON-safe result validation.
+
+## Authentication testing
+
+`createTestAuthSession()` uses the same BCP session token implementation as production auth.
+
+```ts
+const session =
+    await createTestAuthSession(
+        {
+            id: 42,
+        },
+        {
+            secret,
+            store:
+                authSessionStore,
+        }
+    );
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
+```
+
+This avoids introducing a framework-only fake user header.
+
+## Database rollback tests
+
+```ts
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+
+        // assertions
+    }
+);
+```
+
+After the callback succeeds, BCP deliberately rejects the database transaction with an internal rollback signal, then returns the callback result to the test.
+
+## Infrastructure harnesses
+
+`0.2.14` adds thin harnesses over the real platform contracts instead of separate mock implementations:
+
+```text
+BackgroundJobQueue       -> createJobTestHarness()
+Workflow                 -> createWorkflowTestHarness()
+OutboxStore + Dispatcher -> createOutboxTestHarness()
+RealtimeHub              -> createRealtimeTestHarness()
+RealtimeSocket           -> createRealtimeTestSocket()
+```
+
+## SSE
+
+```ts
+const events =
+    await readSseEvents(
+        response,
+        {
+            limit: 1,
+            timeoutMs: 1_000,
+        }
+    );
+```
+
+SSE comments and retry frames are ignored and JSON `data:` payloads are decoded when possible.
+
+## Package/runtime contract
+
+The prepared npm package now exposes:
+
+```text
+bcp/testing
+  types   -> packages/client/src/testing.ts
+  browser -> packages/client/src/server-only.browser.mjs
+  default -> packages/client/src/testing.mjs
+```
+
+`testing.mjs` is compiled during `package:prepare` so Node does not need a TypeScript loader to use the testing entrypoint from an installed package.
+
+## Compatibility
+
+`0.2.14` has no intentional breaking changes from `0.2.13`.
+
+All existing runtime entrypoints remain supported.
+
+## Validation
+
+Before 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 release must not be tagged or published until the final release commit passes the complete RC sequence.
+
+## Non-goals
+
+`0.2.14` does not add:
+
+- a DOM/browser renderer,
+- Playwright integration,
+- component snapshots,
+- a coverage runner,
+- a Jest dependency,
+- a Vitest dependency,
+- automatic Docker/database test provisioning.
+
+These can be layered on top of the base testing contracts in later milestones.