create-bcp-app 0.2.16 → 0.2.17

package/README.md

@@ -34,7 +34,6 @@ For direct PowerShell usage, prefer the collision-free local alias:
 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 +44,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 +66,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.2.16` target:
+Example for the `0.2.17` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.16",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.17",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.16"
+    "version": "0.2.17"
   },
   "packageManager": "npm",
   "presets": {
@@ -109,15 +106,6 @@ For MySQL, PostgreSQL and SQLite, generated `lib/database.ts` exposes BCP databa
 
 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";
-```
-
 ## Background jobs and scheduling
 
 ```ts
@@ -160,12 +148,8 @@ export const onboarding =
     );
 ```
 
-`bcp/workflow` supports sequential/parallel steps, retry, persisted delays, compensation and optional execution through `bcp/jobs`.
-
 ## Transactional Outbox & Events — 0.2.12+
 
-Applications using the SQL Database Platform can persist integration events in the same transaction as business data:
-
 ```ts
 await db.transaction(
     async tx => {
@@ -184,12 +168,8 @@ await db.transaction(
 );
 ```
 
-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:
-
 ```ts
 import {
     createRealtime,
@@ -199,35 +179,10 @@ 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 library. Adapt your selected provider to `RealtimeSocket`. SSE is available directly through `realtime.sse()`.
 
-The memory broker/presence store are local-only. Multi-instance production deployments should provide shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
-
 ## Testing Platform — 0.2.14+
 
-`bcp/testing` adds framework-native test helpers without requiring a specific test runner.
-
-Request/route example:
-
 ```ts
 import {
     createRouteTestHandler,
@@ -256,72 +211,13 @@ await expectResponse(
     });
 ```
 
-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
-);
-```
-
-Rollback database tests:
-
-```ts
-import {
-    withTestTransaction,
-} from "bcp/testing";
-
-await withTestTransaction(
-    db,
-    async tx => {
-        await tx.execute(
-            "INSERT INTO users ..."
-        );
-    }
-);
-```
-
-Infrastructure helpers include:
-
-```text
-createJobTestHarness()
-createWorkflowTestHarness()
-createOutboxTestHarness()
-createRealtimeTestSocket()
-createRealtimeTestHarness()
-readSseEvents()
-createFakeClock()
-createSequenceIdFactory()
-runTestMiddleware()
-```
-
-`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.
+BCP testing helpers are runner-neutral and can be used with Node `node:test`, Vitest, Jest or another runner.
 
 ## Plugin & Module Platform — 0.2.15+
 
-Use `bcp/plugins` to compose reusable server-side application modules with explicit lifecycle and dependencies.
-
 ```ts
 import {
     createPluginHost,
-    defineModule,
     definePlugin,
 } from "bcp/plugins";
 
@@ -344,85 +240,114 @@ const jobsPlugin =
         ],
     });
 
-const backendModule =
-    defineModule({
-        name: "backend",
+export const plugins =
+    createPluginHost({
         plugins: [
-            databasePlugin,
             jobsPlugin,
+            databasePlugin,
         ],
     });
-
-const host =
-    createPluginHost({
-        modules: [
-            backendModule,
-        ],
-    });
-
-await host.start();
 ```
 
-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.
-
-`bcp/plugins` is server-only and cannot be imported into page/client bundles.
-
 ## Cache Platform v2 — 0.2.16+
 
-Use the existing `bcp/cache` entrypoint for provider-neutral shared caching while keeping the original `cache()` and `dedupe()` APIs available.
-
 ```ts
 import {
     createCacheStore,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
 } from "bcp/cache";
 
 export const cache =
-    createCacheStore();
+    createCacheStore({
+        adapter:
+            createRedisCacheAdapter({
+                client: redisClient,
+            }),
+        lock:
+            createRedisCacheLockAdapter({
+                client: redisClient,
+            }),
+    });
 ```
 
-Cache-aside loading:
+BCP does not install or own the Redis client. Applications remain responsible for credentials, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
+
+## Observability Platform v3 — 0.2.17+
+
+Metrics and health remain available through the same entrypoint:
 
 ```ts
-const user =
-    await cache.getOrSet(
-        "user:42",
-        () => loadUser(42),
-        {
-            ttlMs: 60_000,
-            tags: ["users"],
-            paths: ["/users/42"],
-        }
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createTracer,
+} from "bcp/observability";
+```
+
+Create a tracer:
+
+```ts
+export const tracer =
+    createTracer({
+        serviceName: "my-app",
+    });
+```
+
+Trace incoming HTTP requests with Middleware System v2:
+
+```ts
+import {
+    createRequestTracingMiddleware,
+} from "bcp/observability";
+
+export const middleware =
+    createRequestTracingMiddleware(
+        tracer
     );
 ```
 
-For multi-instance deployments, applications can supply Redis-compatible cache and lock adapters:
+The middleware understands W3C `traceparent`, preserves `x-correlation-id`, creates a server span and returns the current trace headers on the response.
+
+For jobs/workflows/events/realtime payloads use explicit trace carriers:
 
 ```ts
 import {
-    createRedisCacheAdapter,
-    createRedisCacheLockAdapter,
-} from "bcp/cache";
+    createTraceCarrier,
+    runWithTraceCarrier,
+} from "bcp/observability";
 
-const redisCache =
-    createRedisCacheAdapter({
-        client: redisClient,
-    });
+const trace =
+    createTraceCarrier();
 
-const redisLock =
-    createRedisCacheLockAdapter({
-        client: redisClient,
-    });
+await jobs.enqueue(
+    "order.process",
+    {
+        orderId,
+        trace,
+    }
+);
+```
 
-export const cache =
-    createCacheStore({
-        adapter: redisCache,
-        lock: redisLock,
-    });
+Consumer:
+
+```ts
+await runWithTraceCarrier(
+    payload.trace,
+    () =>
+        tracer.withSpan(
+            "job order.process",
+            handler,
+            {
+                kind: "consumer",
+            }
+        )
+);
 ```
 
-BCP does not install or own the Redis client. Applications remain responsible for credentials, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
+Use `getTraceLogFields()` to add `traceId`, `spanId` and `correlationId` to structured logs.
 
-`getOrSet()` provides local singleflight and can use distributed lock leases with heartbeat renewal to reduce cache stampedes across instances.
+BCP does not install OpenTelemetry or a vendor APM package. Implement `TraceSpanExporter` when production spans need to be sent to an external collector.
 
 ## Storage providers
 
@@ -462,5 +387,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.17.tgz
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -199,49 +199,6 @@ await expectResponse(
     });
 ```
 
-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
-);
-```
-
-Database tests can force rollback after assertions:
-
-```ts
-import {
-    withTestTransaction,
-} from "bcp/testing";
-
-await withTestTransaction(
-    db,
-    async tx => {
-        await tx.execute(
-            "INSERT INTO users ..."
-        );
-    }
-);
-```
-
-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()`.
-
 BCP does not require Jest or Vitest; these helpers work with Node `node:test` or another runner.
 
 ## Plugin & Module Platform — BCP 0.2.15+
@@ -284,10 +241,6 @@ export const plugins =
 
 Plugin startup follows dependency order and shutdown reverses it. Plugins can use `setup/start/stop/dispose`, config parsers, shared services and async hooks.
 
-Use `defineModule()` when a reusable package needs to bundle multiple plugin definitions into one named module.
-
-`bcp/plugins` is server-only and cannot be imported from page/client bundles.
-
 ## Cache Platform v2 — BCP 0.2.16+
 
 Use `createCacheStore()` for async cache-aside loading, shared adapters and distributed cache-fill coordination.
@@ -341,6 +294,93 @@ export const cache =
 
 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.
 
+## Observability Platform v3 — BCP 0.2.17+
+
+Use the existing `bcp/observability` entrypoint for tracing as well as metrics and health.
+
+```ts
+import {
+    createTracer,
+} from "bcp/observability";
+
+export const tracer =
+    createTracer({
+        serviceName: "my-app",
+    });
+```
+
+Trace incoming Middleware System v2 requests:
+
+```ts
+import {
+    createRequestTracingMiddleware,
+} from "bcp/observability";
+
+export const middleware =
+    createRequestTracingMiddleware(
+        tracer
+    );
+```
+
+The middleware continues valid W3C `traceparent` headers, preserves `x-correlation-id`, creates a server span and includes active trace headers in the response.
+
+Create child spans for application work:
+
+```ts
+await tracer.withSpan(
+    "order.checkout",
+    async () => {
+        await tracer.withSpan(
+            "database.order.insert",
+            createOrder,
+            {
+                kind: "client",
+            }
+        );
+    }
+);
+```
+
+For jobs, workflows, events and realtime payloads, propagate context explicitly:
+
+```ts
+import {
+    createTraceCarrier,
+    runWithTraceCarrier,
+} from "bcp/observability";
+
+const trace =
+    createTraceCarrier();
+
+await jobs.enqueue(
+    "order.process",
+    {
+        orderId,
+        trace,
+    }
+);
+```
+
+Consumer:
+
+```ts
+await runWithTraceCarrier(
+    payload.trace,
+    () =>
+        tracer.withSpan(
+            "job order.process",
+            handler,
+            {
+                kind: "consumer",
+            }
+        )
+);
+```
+
+Use `getTraceLogFields()` to attach `traceId`, `spanId` and `correlationId` to structured logs.
+
+BCP does not install OpenTelemetry or a vendor APM SDK. Production collector integration is application-owned through `TraceSpanExporter`.
+
 ## Generate framework files
 
 ```bash