@chidchanun/bcp 0.2.11 → 0.2.13

package/README.md

@@ -1,55 +1,36 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, background jobs, recurring scheduling, workflow orchestration, observability, validation, uploads, storage and standalone Node.js production 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, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.11 — Workflow Orchestration`
+> **Development target:** `0.2.13 — Realtime Platform`
 >
-> `0.2.11` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.13` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
-## 0.2 platform
-
-`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, `0.2.6` added Authorization & Security v2, `0.2.7` added Observability Platform v2, `0.2.8` added Background Jobs Platform, `0.2.9` added recurring scheduling, `0.2.10` added durable worker leases/DLQ/Redis adapters, and `0.2.11` adds persistent multi-step workflow orchestration.
-
-Machine-readable platform contracts:
-
-```text
-docs/platform-manifest.json
-  -> runtime target, capabilities and compatibility
-
-docs/docs-web-manifest.json
-  -> documentation navigation, routes and releases
-
-docs/api-manifest.json
-  -> public package entrypoints and guide ownership
-```
-
-## Current capabilities
+## Current platform
 
 | Area | Capability |
 | --- | --- |
 | Application | React SSR, hydration, layouts, metadata and SPA navigation |
 | Routing | Static, dynamic, catch-all, optional catch-all and route groups |
-| Server data | Route `loader.ts`, request-scoped server APIs |
-| Mutations | Route-owned `actions.ts` and `<Form>` |
-| Authentication | JWT cookie sessions, optional server-side session stores, revocation, logout-all, idle timeout and rotation |
-| Authorization | Auth/guest/role/permission route guards, flat permissions and resource-aware policies |
-| Request security | Same-origin validation and signed CSRF tokens for unsafe mutations |
+| Server data | Route loaders and request-scoped server APIs |
+| Mutations | Route-owned actions and `<Form>` |
+| Authentication | JWT cookie sessions, optional server-side stores, revocation, logout-all and idle timeout |
+| Authorization | Auth/guest/role/permission guards and resource-aware policies |
+| Security | Same-origin validation and signed CSRF tokens |
 | Middleware | Middleware System v2 with onion execution |
-| Background jobs | Delayed jobs, retries/backoff, cancellation, concurrent workers, visibility leases, heartbeat, stale recovery and DLQ |
-| Scheduling | Recurring interval jobs, UTC cron, schedule-store leases and deterministic scheduled run IDs |
-| Durable jobs | Redis-compatible queue/schedule adapters, retention cleanup, requeue and queue statistics |
-| Workflows | Sequential/parallel steps, retries, persisted delays, compensation, run leases and optional queue-backed execution |
-| Observability | Structured logs, counters/gauges/histograms, Prometheus output, request metrics and health/readiness checks |
-| Validation | Typed validators and structured validation errors |
-| Error handling | HTTP error helpers and consistent error responses |
-| Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Uploads | Buffered multipart helpers and production multipart streaming |
-| Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
+| Database | MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
+| Background jobs | Delay, retry/backoff, cancellation and concurrent workers |
+| Scheduling | Interval/UTC cron schedules and scheduler leases |
+| Durable jobs | Redis-compatible queue/schedule adapters, visibility timeout, heartbeat, stale recovery and DLQ |
+| 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 |
+| 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 |
-| Configuration | Typed `bcp.config.*`, optional `bcp.environment.*`, startup diagnostics and `bcp config check` |
-| Developer tools | Generators, Doctor/Inspect v2, updater, route inspection and project metadata |
-| Production | Standalone Node.js build, application packaging, production dependency pruning, deployment manifests, Docker starter, hardening and graceful shutdown |
-| Documentation | Manifest-driven docs navigation, platform metadata and public API reference |
+| Configuration | Typed config/environment validation and diagnostics |
+| Production | Standalone Node.js build, packaging, dependency pruning, Docker starter and graceful shutdown |
+| Documentation | Manifest-driven docs, platform metadata and API reference |
 
 ## Requirements
 
@@ -57,7 +38,7 @@ docs/api-manifest.json
 - React `19`
 - npm
 
-Database drivers are optional and provider-specific:
+Optional SQL drivers:
 
 ```text
 MySQL       mysql2
@@ -73,7 +54,7 @@ cd my-app
 npm run dev
 ```
 
-Generated projects normally keep one framework dependency key:
+Generated projects normally use one framework dependency:
 
 ```json
 {
@@ -83,314 +64,39 @@ Generated projects normally keep one framework dependency key:
 }
 ```
 
-Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application.
-
-## Configuration & environment
-
-Framework configuration stays in one of:
-
-```text
-bcp.config.ts
-bcp.config.mts
-bcp.config.js
-bcp.config.mjs
-```
-
-Application environment validation can be declared in:
-
-```text
-bcp.environment.ts
-bcp.environment.mts
-bcp.environment.js
-bcp.environment.mjs
-```
-
-Configuration precedence is:
-
-```text
-CLI override
-    ↓
-BCP_* environment
-    ↓
-bcp.config.*
-    ↓
-framework defaults
-```
-
-Validate configuration and declared environment values with:
-
-```bash
-bcp config check
-bcp config check --json
-```
-
-Variables beginning with `BCP_PUBLIC_` may be embedded in browser output. Never expose application secrets through public-prefixed variables.
-
-Read more:
-
-- [Configuration](docs/configuration.md)
-- [Environment Validation](docs/environment-validation.md)
-
-## Database Platform v2 — 0.2.3
+## Core backend entrypoints
 
 ```ts
-import {
-    db,
-    createDatabase,
-} from "bcp/database";
-```
-
-Built-in SQL providers:
-
-```text
-mysql
-postgresql
-sqlite
+import { db } from "bcp/database";
+import { createAuth } from "bcp/auth";
+import { createJobQueue } from "bcp/jobs";
+import { createWorkflow } from "bcp/workflow";
+import { createTransactionalOutbox } from "bcp/events";
+import { createRealtime } from "bcp/realtime";
+import { createMetricsRegistry } from "bcp/observability";
 ```
 
-Migration CLI:
-
-```bash
-bcp db create create_users
-bcp db migrate
-bcp db status
-bcp db rollback
-```
-
-Read more:
-
-- [Database](docs/database.md)
-- [Database Migrations](docs/database-migrations.md)
-
-## Application Packaging — 0.2.4
-
-Create a fresh production build and deployment package:
-
-```bash
-bcp package
-```
-
-Output is written under:
-
-```text
-.bcp-framework/package/
-```
-
-Read more:
-
-- [Application Packaging](docs/application-packaging.md)
-- [Deployment](docs/deployment.md)
-
-## Authentication Platform v2 — 0.2.5
-
-```ts
-import {
-    auth,
-    createAuth,
-    createMemoryAuthSessionStore,
-    login,
-    logout,
-} from "bcp/auth";
-```
-
-Stateless signed JWT-cookie authentication remains supported. Applications that need centralized revocation can configure an `AuthSessionStore`.
-
-Read more:
-
-- [Authentication](docs/authentication.md)
-- [Auth Session Stores](docs/auth-session-store.md)
-- [Auth Route Guards](docs/auth-route-guards.md)
-
-## Authorization & Security v2 — 0.2.6
-
-```ts
-import {
-    authorize,
-    hasPermission,
-    requirePermission,
-} from "bcp/auth";
-```
-
-Request-security helpers are exposed from `bcp/server`:
-
-```ts
-import {
-    createCsrfToken,
-    requireCsrfRequest,
-    requireSameOriginRequest,
-} from "bcp/server";
-```
-
-Read more: [Authorization & Security v2](docs/authorization-security.md)
-
-## Observability Platform v2 — 0.2.7
-
-```ts
-import {
-    createHealthRegistry,
-    createMetricsRegistry,
-    createMetricsResponse,
-} from "bcp/observability";
-```
-
-Read more: [Observability Platform v2](docs/observability.md)
-
-## Background Jobs Platform — 0.2.8
+## Durable jobs and scheduling
 
 ```ts
 import {
     createJobQueue,
-} from "bcp/jobs";
-
-export const jobs =
-    createJobQueue();
-```
-
-Register work:
-
-```ts
-jobs.register<{
-    userId: number;
-}>(
-    "email.welcome",
-    async ({ payload }) => {
-        await sendWelcomeEmail(
-            payload.userId
-        );
-    }
-);
-```
-
-Enqueue work:
-
-```ts
-await jobs.enqueue(
-    "email.welcome",
-    {
-        userId: 42,
-    },
-    {
-        delayMs: 5_000,
-        maxAttempts: 5,
-    }
-);
-```
-
-Read more: [Background Jobs Platform](docs/background-jobs.md)
-
-## Job Scheduling Platform — 0.2.9
-
-```ts
-import {
     createJobScheduler,
 } from "bcp/jobs";
 
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-    });
-```
-
-Interval schedule:
-
-```ts
-await scheduler.schedule(
-    "cache.cleanup",
-    {},
-    {
-        id: "cache-cleanup",
-        everyMs: 5 * 60 * 1000,
-    }
-);
-```
-
-UTC cron schedule:
-
-```ts
-await scheduler.schedule(
-    "report.weekday",
-    {},
-    {
-        cron: "30 9 * * 1-5",
-    }
-);
-```
-
-Read more: [Job Scheduling Platform](docs/job-scheduling.md)
-
-## Durable Jobs Platform — 0.2.10
-
-Workers support visibility leases, heartbeat renewal and stale-running recovery when the configured adapter implements those capabilities:
-
-```ts
-const worker =
-    jobs.startWorker({
-        workerId: "email-worker",
-        concurrency: 4,
-        visibilityTimeoutMs: 30_000,
-        heartbeatIntervalMs: 10_000,
-        pollIntervalMs: 250,
-    });
-```
-
-Retry-exhausted jobs can be inspected and requeued:
-
-```ts
-const failed =
-    await jobs.deadLetters();
-
-await jobs.requeueDeadLetter(
-    failed[0].id,
-    {
-        delayMs: 5_000,
-        resetAttempts: true,
-    }
-);
-```
-
-Redis-compatible durable adapters:
-
-```ts
-import {
-    createJobQueue,
-    createJobScheduler,
-    createRedisJobQueueAdapter,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
-
-const queueAdapter =
-    createRedisJobQueueAdapter({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
-
 export const jobs =
-    createJobQueue({
-        adapter: queueAdapter,
-    });
-
-const scheduleStore =
-    createRedisJobScheduleStore({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
+    createJobQueue();
 
 export const scheduler =
     createJobScheduler({
         queue: jobs,
-        store: scheduleStore,
-        ownerId: "scheduler-a",
     });
 ```
 
-BCP does not read `REDIS_URL` or own the Redis client connection lifecycle automatically.
-
-Read more: [Durable Jobs Platform](docs/durable-jobs.md)
+Production adapters can provide Redis-compatible durable queue/schedule storage without BCP owning the Redis connection.
 
 ## Workflow Orchestration — 0.2.11
 
-Create a server-only workflow with typed input:
-
 ```ts
 import {
     createWorkflow,
@@ -404,11 +110,7 @@ export const onboarding =
         workflow => {
             workflow.step(
                 "profile",
-                async ({ input }) => {
-                    await createProfile(
-                        input.userId
-                    );
-                }
+                createProfile
             );
 
             workflow.parallel(
@@ -433,66 +135,199 @@ export const onboarding =
     );
 ```
 
-Per-step retries:
+Workflows support retries, compensation, persisted delays and optional durable queue execution.
+
+## Transactional Outbox & Events — 0.2.12
+
+Use the same SQL transaction for business data and its outbox event:
 
 ```ts
-workflow.step(
-    "charge-card",
-    chargeCard,
-    {
-        maxAttempts: 3,
-        retryDelayMs:
-            attempt =>
-                attempt * 1_000,
+await db.transaction(
+    async tx => {
+        await tx.execute(
+            "INSERT INTO orders ..."
+        );
+
+        await outbox.publish(
+            tx,
+            "order.created",
+            {
+                orderId: 42,
+            }
+        );
     }
 );
 ```
 
-Saga-style compensation:
+After commit, an outbox dispatcher can deliver through `bcp/jobs`, a custom publisher or the local event bus.
+
+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,
+} from "bcp/realtime";
+
+export const realtime =
+    createRealtime();
+```
+
+### Channels / rooms
 
 ```ts
-workflow.step(
-    "reserve-stock",
-    reserveStock,
+const connection =
+    await realtime.connect();
+
+await connection.join(
+    "orders:42"
+);
+
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
     {
-        compensate:
-            releaseStock,
+        status: "paid",
     }
 );
 ```
 
-A failed run can be compensated in reverse completion order:
+Rooms are represented by channel names. Connections receive broadcasts only for channels they joined.
+
+### Presence
 
 ```ts
-await onboarding.compensate(
-    runId
+await connection.join(
+    "project:7",
+    {
+        presence: {
+            status: "online",
+        },
+    }
 );
+
+const members =
+    await realtime.members(
+        "project:7"
+    );
 ```
 
-For durable execution, supply an existing BCP job queue and a shared workflow store:
+The built-in memory presence store is process-local. Multi-instance deployments should provide a shared `RealtimePresenceStore`.
+
+### Authentication and private channels
 
 ```ts
-export const fulfillment =
-    createWorkflow(
-        "order.fulfillment",
-        defineWorkflow,
+const realtime =
+    createRealtime({
+        authenticate:
+            async ({ request }) =>
+                request
+                    ? loadRealtimeUser(
+                        request
+                    )
+                    : null,
+
+        getUserId:
+            user => user.id,
+
+        authorizeChannel:
+            ({ connection, channel }) =>
+                !channel.startsWith(
+                    "private:"
+                ) ||
+                Boolean(
+                    connection.user
+                ),
+    });
+```
+
+### WebSocket provider contract
+
+BCP intentionally does not install `ws`, Socket.IO or another WebSocket server dependency.
+
+Adapt the selected server/provider to `RealtimeSocket`, then attach it:
+
+```ts
+const connection =
+    await realtime.attachSocket(
+        socketAdapter,
         {
-            queue: jobs,
-            store:
-                workflowStore,
+            request,
         }
     );
 ```
 
-With a queue configured, `start()`, `retry()`, `resume()` and delay continuations execute through `bcp/jobs`. `WorkflowStore.claim()` is the atomic run-level concurrency boundary for multi-instance deployments.
+The JSON socket protocol supports `join`, `leave`, `event` and `ping` messages.
 
-The built-in `createMemoryWorkflowStore()` is intended for local development and tests. External side effects should remain idempotent because durable job delivery is at-least-once.
+### Server-Sent Events
 
-Read more: [Workflow Orchestration](docs/workflow-orchestration.md)
+SSE is built in through Web `Response`:
 
-## Public entrypoints
+```ts
+export function GET(
+    request: Request
+) {
+    return realtime.sse(
+        "workflow:42",
+        {
+            signal:
+                request.signal,
+        }
+    );
+}
+```
+
+### Cross-instance delivery
+
+`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.
+
+```text
+Browser A -> App A ----\
+                       Shared Broker
+Browser B -> App B ----/
+          |             |
+          +---- Shared Presence Store
+```
+
+### Heartbeat
+
+```ts
+const heartbeat =
+    realtime.startHeartbeat({
+        intervalMs: 20_000,
+    });
+
+// shutdown
+await heartbeat.stop();
+await realtime.close();
+```
 
-The current `0.2.x` platform contract recognizes:
+`realtime.ping` / `realtime.pong` and `sweepStale()` provide connection liveness cleanup.
+
+### Jobs / workflows / events integration
+
+Realtime is the transient delivery edge for durable backend state:
+
+```ts
+await realtime.broadcast(
+    `jobs:${job.id}`,
+    "job.progress",
+    {
+        progress: 60,
+    }
+);
+```
+
+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.
+
+Read more: [Realtime Platform](docs/realtime-platform.md)
+
+## Public entrypoints
 
 ```text
 bcp
@@ -505,24 +340,18 @@ bcp/database
 bcp/auth
 bcp/jobs
 bcp/workflow
+bcp/events
+bcp/realtime
 bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-Application code should use public entrypoints instead of importing framework internals under `packages/`.
-
-See:
-
-- [API Reference](docs/api-reference.md)
-- [Platform Manifest](docs/platform-manifest.json)
-- [API Manifest](docs/api-manifest.json)
+Application code should use public entrypoints instead of private `packages/*` implementation files.
 
 ## CLI
 
-Core commands:
-
 ```bash
 bcp dev
 bcp build
@@ -545,7 +374,7 @@ bcp db status
 bcp db rollback
 ```
 
-Project generators:
+Generators:
 
 ```bash
 bcp generate page dashboard/users
@@ -557,27 +386,24 @@ bcp generate migration create_users
 ## Production model
 
 ```text
-Browser / API clients
-        ↓
-security + middleware + auth
-        ↓
-loaders / actions / API routes
-        ↓
-SSR / application responses
-
-Operational side channels:
-workflow orchestration
-        ↓
-shared jobs + scheduler
-        ↓
-workers + structured logs + metrics + health/readiness
+Browser / API / Realtime clients
+              |
+      security + auth
+              |
+       application APIs
+       /      |       \
+ database  workflows  realtime
+    |          |         ^
+ outbox       jobs       |
+    \__________|_________/
+           durable state
 ```
 
-Raw standalone build:
+## Packaging
 
 ```bash
 npm run build
-npm run start
+npm start
 ```
 
 Deployment package:
@@ -588,33 +414,30 @@ bcp package
 
 ## Documentation Platform
 
-The framework repository is the documentation source of truth.
-
-`bcp-docs-web` consumes:
+Machine-readable contracts:
 
 ```text
-docs/docs-web-manifest.json
 docs/platform-manifest.json
+docs/docs-web-manifest.json
 docs/api-manifest.json
 ```
 
 ## Release validation
 
-Framework releases must pass:
+Before publishing `0.2.13`:
 
 ```bash
-npm install
 npm run typecheck
 npm run test:unit
 npm run test:integration
-npm run test:package
 npm run test:e2e
+npm run test:package
 npm run rc:check
 ```
 
-`0.2.11` adds Workflow Orchestration unit and prepared-package smoke checks covering sequential/parallel execution, retries, persisted delay/resume behavior, compensation, queue-backed continuation, run leases, browser boundary enforcement and the compiled `bcp/workflow` runtime.
+`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.
 
-Do not tag or publish until the final release commit passes the complete RC sequence.
+Do not tag or publish until the exact final release commit passes the full RC sequence.
 
 ## Release history
 
@@ -638,12 +461,16 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.9` | Job Scheduling Platform |
 | `0.2.10` | Durable Jobs Platform |
 | `0.2.11` | Workflow Orchestration |
+| `0.2.12` | Transactional Outbox & Events |
+| `0.2.13` | Realtime Platform |
 
 ## Roadmap
 
-`0.2.11 — Workflow Orchestration` establishes persistent multi-step backend workflows on top of the provider-neutral jobs foundation.
+`0.2.13` establishes provider-neutral live delivery on top of the durable database/outbox/jobs/workflow stack.
+
+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 `0.2.x` milestone is transactional outbox/event delivery so a database change and later asynchronous workflow/job publication can be coordinated without pretending a Redis publish is part of the database transaction. Realtime, testing, plugin/module and broader deployment work remain later roadmap items. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+Native desktop/mobile compilation remains later roadmap work.
 
 ## License