create-bcp-app 0.2.11 → 0.2.12

package/README.md

@@ -28,16 +28,6 @@ Generated npm scripts use `bcp` because npm places `node_modules/.bin` on the sc
 }
 ```
 
-When Tailwind CSS is selected, the generated packaging script preserves the production CSS step:
-
-```json
-{
-  "scripts": {
-    "package": "npm run css:build:prod && bcp package"
-  }
-}
-```
-
 For direct PowerShell usage, prefer the collision-free local alias:
 
 ```powershell
@@ -75,27 +65,21 @@ Select storage provider:
   Cloudflare R2
 ```
 
-Equivalent non-interactive flags are available for CI/scaffolding automation.
-
 ## Generated project metadata
 
-New projects include:
+New projects include `bcp.project.json`.
 
-```text
-bcp.project.json
-```
-
-Example:
+Example for the `0.2.12` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.11",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.12",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.11"
+    "version": "0.2.12"
   },
   "packageManager": "npm",
   "presets": {
@@ -109,43 +93,9 @@ Example:
 
 This manifest records scaffold identity only. It must not contain secrets and should normally be committed to source control.
 
-## Generated application defaults
-
-Generated applications include the project-root `@/` alias and TypeScript settings compatible with the BCP bundler.
-
-Modules that use React client hooks such as `useState` or `useEffect` must declare `"use client"` at the top of the module.
-
-The generated BCP dependency is pinned to the exact framework release selected by the generator.
-
-Update later with:
-
-```bash
-npm run update
-```
-
-Check without modifying files:
-
-```powershell
-npm exec -- bcp-framework update --check
-```
-
-## Tailwind CSS
-
-When Tailwind is enabled, the project includes `tailwindcss`, `@tailwindcss/cli`, `concurrently`, `app/globals.css`, `/bcp.css` stylesheet setup and starter utility classes.
-
-Generated commands include:
-
-```text
-npm run css:build
-npm run css:watch
-npm run css:build:prod
-```
-
-`npm run build` and `npm run package` create the production stylesheet before the BCP production build/package flow.
-
 ## Database presets
 
-The database choice adds starter configuration and the matching driver:
+Database choices add starter configuration and the matching driver:
 
 - MySQL: `mysql2`
 - PostgreSQL: `pg`
@@ -153,71 +103,31 @@ The database choice adds starter configuration and the matching driver:
 - MongoDB: `mongodb`
 - None: no database dependency
 
-For **MySQL**, **PostgreSQL** and **SQLite**, generated `lib/database.ts` exposes framework database primitives through `bcp/database`.
-
-The generator intentionally does not force an ORM.
-
-## Storage providers
-
-Selecting a storage provider creates `lib/storage.ts` and provider-specific environment settings. Supported presets are Local Server, Amazon S3 and Cloudflare R2.
-
-Storage credentials are server-only. Do not expose them through `BCP_PUBLIC_*` variables.
-
-## JWT Cookie authentication
-
-Selecting `JWT Cookie` creates `lib/auth.ts` and starter `/api/auth/login`, `/logout` and `/me` routes, and adds:
-
-```dotenv
-BCP_SESSION_SECRET=
-```
-
-Set this to a cryptographically random secret of at least 32 bytes before real authentication use.
+For MySQL, PostgreSQL and SQLite, generated `lib/database.ts` exposes BCP database primitives through `bcp/database`.
 
-BCP `0.2.5+` can opt into revocable server-side auth state through `AuthSessionStore`.
+## Authentication and security
 
-## Authorization & request security — 0.2.6+
+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.
 
-Generated applications can use permission guards and resource policies from `bcp/auth`, plus same-origin and CSRF protection from `bcp/server`.
-
-Authorization and CSRF checks must remain on the server; hiding UI controls in client code is not an authorization boundary.
-
-## Observability — 0.2.7+
-
-Generated projects can opt into process-local metrics and health/readiness without adding another dependency:
+## Observability
 
 ```ts
 import {
     createHealthRegistry,
     createMetricsRegistry,
-    createRequestMetricsMiddleware,
 } from "bcp/observability";
 ```
 
-`bcp/observability` is server-only. Protect metrics and operational health detail with an appropriate network or authorization boundary when needed.
-
-## Background jobs — 0.2.8+
-
-Generated projects can create a server-only background job queue:
+## Background jobs and scheduling
 
 ```ts
 import {
     createJobQueue,
+    createJobScheduler,
 } from "bcp/jobs";
 
 export const jobs =
     createJobQueue();
-```
-
-Workers support concurrency, delayed jobs, retry/backoff and cancellation.
-
-## Job scheduling — 0.2.9+
-
-Recurring schedules use the same `bcp/jobs` entrypoint:
-
-```ts
-import {
-    createJobScheduler,
-} from "bcp/jobs";
 
 export const scheduler =
     createJobScheduler({
@@ -225,82 +135,23 @@ export const scheduler =
     });
 ```
 
-Interval schedule:
-
-```ts
-await scheduler.schedule(
-    "cache.cleanup",
-    {},
-    {
-        everyMs: 300_000,
-    }
-);
-```
-
-UTC cron schedule:
-
-```ts
-await scheduler.schedule(
-    "report.weekday",
-    {},
-    {
-        cron: "30 9 * * 1-5",
-    }
-);
-```
-
-## Durable jobs — 0.2.10+
-
-BCP `0.2.10` adds worker visibility leases, heartbeat renewal, stale-running recovery, DLQ/requeue, retention cleanup and queue statistics.
-
-```ts
-const worker =
-    jobs.startWorker({
-        workerId: "worker-a",
-        concurrency: 4,
-        visibilityTimeoutMs: 30_000,
-        heartbeatIntervalMs: 10_000,
-    });
-```
-
-BCP intentionally does not install a Redis client library. Applications own the Redis connection and can pass a minimal `RedisCommandClient` to `createRedisJobQueueAdapter()` and `createRedisJobScheduleStore()`.
-
-`bcp/jobs` is server-only and must not be imported into page/client bundles.
+`0.2.10+` adds visibility leases, heartbeat renewal, stale-running recovery, DLQ/requeue, retention cleanup and Redis-compatible durable adapters.
 
 ## Workflow orchestration — 0.2.11+
 
-Generated applications can define persistent backend workflows with the new server-only `bcp/workflow` entrypoint:
-
 ```ts
 import {
     createWorkflow,
 } from "bcp/workflow";
 
 export const onboarding =
-    createWorkflow<{
-        userId: number;
-    }>(
+    createWorkflow(
         "user.onboarding",
         workflow => {
             workflow.step(
                 "profile",
                 createProfile
             );
-
-            workflow.parallel(
-                "initialize",
-                parallel => {
-                    parallel.step(
-                        "preferences",
-                        createPreferences
-                    );
-                    parallel.step(
-                        "workspace",
-                        createWorkspace
-                    );
-                }
-            );
-
             workflow.delay(
                 "cooldown",
                 1_000
@@ -309,45 +160,92 @@ export const onboarding =
     );
 ```
 
-Step-level retry and compensation are supported:
+`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
-workflow.step(
-    "reserve-stock",
-    reserveStock,
-    {
-        maxAttempts: 3,
-        retryDelayMs: 1_000,
-        compensate:
-            releaseStock,
+import {
+    db,
+} from "bcp/database";
+
+import {
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
+
+const outboxStore =
+    createSqlOutboxStore({
+        database: db,
+        driver: "mysql",
+    });
+
+const outbox =
+    createTransactionalOutbox({
+        store: outboxStore,
+    });
+
+await db.transaction(
+    async tx => {
+        await tx.execute(
+            "INSERT INTO orders ..."
+        );
+
+        await outbox.publish(
+            tx,
+            "order.created",
+            {
+                orderId: 42,
+            }
+        );
     }
 );
 ```
 
-For durable queue-backed execution, pass an existing `BackgroundJobQueue` and a durable shared `WorkflowStore`:
+Create migration SQL with:
 
 ```ts
-const fulfillment =
-    createWorkflow(
-        "order.fulfillment",
-        defineWorkflow,
-        {
-            queue: jobs,
-            store:
-                workflowStore,
-        }
+import {
+    createOutboxMigrationSql,
+} from "bcp/events";
+
+const migrationSql =
+    createOutboxMigrationSql(
+        "mysql"
     );
 ```
 
-The built-in `createMemoryWorkflowStore()` is intended for development/tests. Multi-instance production stores should make `claim()` atomic so only one executor owns a workflow run lease at a time.
+After commit, dispatch to the durable job queue:
 
-External side effects should remain idempotent because durable queue execution is at-least-once.
+```ts
+import {
+    createOutboxDispatcher,
+} from "bcp/events";
 
-`bcp/workflow` is server-only and cannot be imported into page/client bundles.
+const dispatcher =
+    createOutboxDispatcher({
+        store: outboxStore,
+        queue: jobs,
+        ownerId: "outbox-a",
+    });
+
+const runner =
+    dispatcher.start();
+```
 
-## Application Packaging — 0.2.4+
+Event type `order.created` is handed off to queue name `event.order.created`.
 
-Generated projects include:
+The outbox dispatcher supports leases, stale recovery, retry/backoff, custom publishers, a local EventBus, cleanup and statistics.
+
+`bcp/events` is server-only. The SQL outbox protects the database-commit/external-publish boundary, but downstream delivery remains at-least-once, so non-repeatable side effects should use idempotency protection.
+
+## Storage providers
+
+Supported presets are Local Server, Amazon S3 and Cloudflare R2. Storage credentials are server-only and must not use `BCP_PUBLIC_*` variables.
+
+## Application packaging
 
 ```bash
 npm run package
@@ -355,7 +253,7 @@ npm run package
 
 The deployment package excludes application `devDependencies` and project `.env` values. Supply real secrets through the deployment environment.
 
-## Project generators after creation
+## Project generators
 
 ```bash
 npm run generate -- page dashboard/users
@@ -364,15 +262,6 @@ npm run generate -- middleware
 npm run generate -- migration create_users
 ```
 
-Equivalent direct CLI:
-
-```bash
-bcp generate page dashboard/users
-bcp generate api users
-bcp generate middleware
-bcp generate migration create_users
-```
-
 ## Options
 
 ```text
@@ -387,8 +276,8 @@ bcp generate migration create_users
 -h, --help                Show help
 ```
 
-The `--bcp` option is mainly for prerelease/local package verification:
+For prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.11.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.12.tgz
 ```

package/package.json

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

package/template/README.md

@@ -12,8 +12,6 @@ Open `http://localhost:3000`.
 
 ## Project commands
 
-Generated projects use the project-local BCP Framework CLI through npm scripts:
-
 ```bash
 npm run dev
 npm run routes
@@ -25,25 +23,17 @@ npm start
 npm run update
 ```
 
-The generated scripts call commands such as `bcp dev`, `bcp generate`, `bcp build`, `bcp package` and `bcp start`.
-
 ## Project metadata
 
-Projects created with BCP `0.1.29+` include `bcp.project.json` with non-secret scaffold metadata.
-
-Commit this file with the project. Do not put passwords, access keys, session secrets or tokens in it.
+Generated projects include `bcp.project.json` with non-secret scaffold metadata. Commit it with the project, but never put passwords, tokens or access keys in it.
 
 ## Authentication — BCP 0.2.5+
 
-Projects created with the `JWT Cookie` preset remain stateless by default and use the generated `lib/auth.ts` helpers.
-
-BCP Authentication Platform v2 can opt into revocable server-side session state with `createAuth()` and `AuthSessionStore`.
+JWT Cookie projects can opt into revocable server-side session state with `createAuth()` and `AuthSessionStore`.
 
 ## Authorization & request security — BCP 0.2.6+
 
-Use permission guards and resource policies from `bcp/auth`, and same-origin/CSRF protection from `bcp/server`.
-
-Authorization must always be enforced server-side. Client UI visibility is not a security boundary.
+Use permission guards/resource policies from `bcp/auth`, and same-origin/CSRF protection from `bcp/server`. Authorization must remain server-side.
 
 ## Observability — BCP 0.2.7+
 
@@ -51,16 +41,11 @@ Authorization must always be enforced server-side. Client UI visibility is not a
 import {
     createHealthRegistry,
     createMetricsRegistry,
-    createRequestMetricsMiddleware,
 } from "bcp/observability";
 ```
 
-Protect operational endpoints when their contents should not be public.
-
 ## Background jobs — BCP 0.2.8+
 
-Create a server-only background queue:
-
 ```ts
 import {
     createJobQueue,
@@ -70,21 +55,6 @@ export const jobs =
     createJobQueue();
 ```
 
-Register typed work:
-
-```ts
-jobs.register<{
-    userId: number;
-}>(
-    "email.welcome",
-    async ({ payload }) => {
-        await sendWelcomeEmail(
-            payload.userId
-        );
-    }
-);
-```
-
 ## Job scheduling — BCP 0.2.9+
 
 ```ts
@@ -98,21 +68,9 @@ export const scheduler =
     });
 ```
 
-Example UTC cron schedule:
-
-```ts
-await scheduler.schedule(
-    "report.weekday",
-    {},
-    {
-        cron: "30 9 * * 1-5",
-    }
-);
-```
-
 ## Durable jobs — BCP 0.2.10+
 
-Workers can use visibility leases, heartbeat renewal and stale-running recovery:
+Workers can use visibility leases, heartbeat renewal, stale recovery and DLQ/requeue. Redis-compatible adapters are available without forcing a Redis client dependency.
 
 ```ts
 const worker =
@@ -124,132 +82,21 @@ const worker =
     });
 ```
 
-Retry-exhausted jobs are available through the adapter DLQ contract:
-
-```ts
-const deadLetters =
-    await jobs.deadLetters();
-
-await jobs.requeueDeadLetter(
-    deadLetters[0].id,
-    {
-        resetAttempts: true,
-    }
-);
-```
-
-Operational helpers:
-
-```ts
-await jobs.recoverStale();
-const stats = await jobs.stats();
-await jobs.cleanup({
-    before:
-        Date.now() -
-        7 * 24 * 60 * 60 * 1000,
-});
-```
-
-### Redis-compatible adapters
-
-BCP does not install a Redis library. Supply an application-owned command client:
-
-```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
-```
-
-Create a durable queue:
-
-```ts
-import {
-    createJobQueue,
-    createRedisJobQueueAdapter,
-} from "bcp/jobs";
-
-const adapter =
-    createRedisJobQueueAdapter({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
-
-export const jobs =
-    createJobQueue({
-        adapter,
-    });
-```
-
-Create a shared schedule store:
-
-```ts
-import {
-    createJobScheduler,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
-
-const store =
-    createRedisJobScheduleStore({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
-
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-        store,
-        ownerId: "scheduler-a",
-    });
-```
-
-A typical deployment may use:
-
-```dotenv
-REDIS_URL=redis://localhost:6379
-```
-
-BCP does not read this variable automatically. The application owns Redis connection creation, credentials, TLS/Cluster configuration and shutdown.
-
-The processing model is at-least-once, so side-effecting job handlers should be idempotent when duplicate execution is unsafe.
-
-`bcp/jobs` is server-only and cannot be imported into page/client bundles.
-
 ## Workflow orchestration — BCP 0.2.11+
 
-Define persistent server-side workflows through `bcp/workflow`:
-
 ```ts
 import {
     createWorkflow,
 } from "bcp/workflow";
 
 export const onboarding =
-    createWorkflow<{
-        userId: number;
-    }>(
+    createWorkflow(
         "user.onboarding",
         workflow => {
             workflow.step(
                 "profile",
                 createProfile
             );
-
-            workflow.parallel(
-                "initialize",
-                parallel => {
-                    parallel.step(
-                        "preferences",
-                        createPreferences
-                    );
-                    parallel.step(
-                        "workspace",
-                        createWorkspace
-                    );
-                }
-            );
-
             workflow.delay(
                 "cooldown",
                 1_000
@@ -258,41 +105,86 @@ export const onboarding =
     );
 ```
 
-Step retry and compensation:
+Workflows support sequential/parallel steps, retries, persisted delays, compensation, run leases and optional durable queue execution.
+
+## Transactional Outbox & Events — BCP 0.2.12+
+
+Use `bcp/events` when application data and an integration event must commit atomically in the same SQL transaction.
 
 ```ts
-workflow.step(
-    "reserve-stock",
-    reserveStock,
-    {
-        maxAttempts: 3,
-        retryDelayMs: 1_000,
-        compensate:
-            releaseStock,
+import {
+    db,
+} from "bcp/database";
+
+import {
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
+
+const outboxStore =
+    createSqlOutboxStore({
+        database: db,
+        driver: "mysql",
+    });
+
+const outbox =
+    createTransactionalOutbox({
+        store: outboxStore,
+    });
+
+await db.transaction(
+    async tx => {
+        await tx.execute(
+            "INSERT INTO orders ..."
+        );
+
+        await outbox.publish(
+            tx,
+            "order.created",
+            {
+                orderId: 42,
+            }
+        );
     }
 );
 ```
 
-For queue-backed execution:
+Generate the required table SQL:
 
 ```ts
-const fulfillment =
-    createWorkflow(
-        "order.fulfillment",
-        defineWorkflow,
-        {
-            queue: jobs,
-            store:
-                workflowStore,
-        }
+import {
+    createOutboxMigrationSql,
+} from "bcp/events";
+
+const sql =
+    createOutboxMigrationSql(
+        "mysql"
     );
 ```
 
-The default `createMemoryWorkflowStore()` is for local development/tests. Multi-instance production deployments should implement a shared durable `WorkflowStore` with atomic `claim()` behavior.
+Dispatch committed events to the durable queue:
+
+```ts
+import {
+    createOutboxDispatcher,
+} from "bcp/events";
+
+const dispatcher =
+    createOutboxDispatcher({
+        store: outboxStore,
+        queue: jobs,
+        ownerId: "outbox-a",
+    });
+
+const runner =
+    dispatcher.start();
+```
+
+Event `order.created` is queued as `event.order.created`.
 
-Workflow handlers that perform external side effects should be idempotent because durable job execution is at-least-once.
+The dispatcher supports leases, stale recovery, retry/backoff, custom publishers, local EventBus delivery, retention cleanup and statistics.
 
-`bcp/workflow` is server-only and cannot be imported into page/client bundles.
+`bcp/events` is server-only. Outbox delivery remains at-least-once, so non-repeatable downstream side effects should use idempotency protection.
 
 ## Generate framework files
 
@@ -303,22 +195,9 @@ npm run generate -- middleware
 npm run generate -- migration create_users
 ```
 
-Equivalent direct commands:
-
-```bash
-bcp generate page dashboard/users
-bcp generate api users
-bcp generate middleware
-bcp generate migration create_users
-```
-
-Existing page/API/middleware targets are not replaced unless `--force` is supplied explicitly.
-
 ## Direct CLI usage
 
-BCP Framework is installed as a project-local dependency.
-
-For PowerShell direct usage:
+For PowerShell:
 
 ```powershell
 npm exec -- bcp-framework --version
@@ -330,8 +209,6 @@ npm exec -- bcp-framework build
 npm exec -- bcp-framework package
 ```
 
-Microsoft SQL Server can install another Windows executable named `bcp.exe`, so the `bcp-framework` alias avoids that command-name collision.
-
 ## Production build
 
 ```bash
@@ -339,12 +216,10 @@ npm run build
 npm start
 ```
 
-## Deployment package — BCP 0.2.4+
+## Deployment package
 
 ```bash
 npm run package
 ```
 
-The output is written to `.bcp-framework/package/` and contains standalone output, production dependency metadata, deployment/environment manifests, integrity hashes and a starter Dockerfile.
-
-BCP intentionally excludes project `.env` files and application `devDependencies` from the deployment package. Provide secrets through your deployment environment.
+BCP excludes project `.env` files and application `devDependencies` from the deployment package. Supply secrets through the deployment environment.