create-bcp-app 0.2.10 → 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:
-
-```text
-bcp.project.json
-```
+New projects include `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.10",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.12",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.10"
+    "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`.
+For MySQL, PostgreSQL and SQLite, generated `lib/database.ts` exposes BCP database primitives through `bcp/database`.
 
-The generator intentionally does not force an ORM.
+## Authentication and security
 
-## 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=
-```
+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.
 
-Set this to a cryptographically random secret of at least 32 bytes before real authentication use.
-
-BCP `0.2.5+` can opt into revocable server-side auth state through `AuthSessionStore`.
-
-## Authorization & request security — 0.2.6+
-
-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,129 +135,117 @@ export const scheduler =
     });
 ```
 
-Interval schedule:
+`0.2.10+` adds visibility leases, heartbeat renewal, stale-running recovery, DLQ/requeue, retention cleanup and Redis-compatible durable adapters.
 
-```ts
-await scheduler.schedule(
-    "cache.cleanup",
-    {},
-    {
-        everyMs: 300_000,
-    }
-);
-```
-
-UTC cron schedule:
+## Workflow orchestration — 0.2.11+
 
 ```ts
-await scheduler.schedule(
-    "report.weekday",
-    {},
-    {
-        cron: "30 9 * * 1-5",
-    }
-);
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+export const onboarding =
+    createWorkflow(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
 ```
 
-## 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.
+`bcp/workflow` supports sequential/parallel steps, retry, persisted delays, compensation and optional execution through `bcp/jobs`.
 
-```ts
-const worker =
-    jobs.startWorker({
-        workerId: "worker-a",
-        concurrency: 4,
-        visibilityTimeoutMs: 30_000,
-        heartbeatIntervalMs: 10_000,
-    });
-```
+## Transactional Outbox & Events — 0.2.12+
 
-Inspect failed jobs:
+Applications using the SQL Database Platform can persist integration events in the same transaction as business data:
 
 ```ts
-const deadLetters =
-    await jobs.deadLetters();
-```
+import {
+    db,
+} from "bcp/database";
+
+import {
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
+
+const outboxStore =
+    createSqlOutboxStore({
+        database: db,
+        driver: "mysql",
+    });
 
-Requeue:
+const outbox =
+    createTransactionalOutbox({
+        store: outboxStore,
+    });
 
-```ts
-await jobs.requeueDeadLetter(
-    deadLetters[0].id,
-    {
-        resetAttempts: true,
+await db.transaction(
+    async tx => {
+        await tx.execute(
+            "INSERT INTO orders ..."
+        );
+
+        await outbox.publish(
+            tx,
+            "order.created",
+            {
+                orderId: 42,
+            }
+        );
     }
 );
 ```
 
-### Redis-compatible durable adapters
-
-BCP intentionally does not install a Redis client library. Applications own the Redis connection and pass a minimal command client to BCP:
-
-```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
-```
-
-Queue adapter:
+Create migration SQL with:
 
 ```ts
 import {
-    createJobQueue,
-    createRedisJobQueueAdapter,
-} from "bcp/jobs";
-
-const adapter =
-    createRedisJobQueueAdapter({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
+    createOutboxMigrationSql,
+} from "bcp/events";
 
-export const jobs =
-    createJobQueue({
-        adapter,
-    });
+const migrationSql =
+    createOutboxMigrationSql(
+        "mysql"
+    );
 ```
 
-Scheduler store:
+After commit, dispatch to the durable job queue:
 
 ```ts
 import {
-    createJobScheduler,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
-
-const store =
-    createRedisJobScheduleStore({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
+    createOutboxDispatcher,
+} from "bcp/events";
 
-export const scheduler =
-    createJobScheduler({
+const dispatcher =
+    createOutboxDispatcher({
+        store: outboxStore,
         queue: jobs,
-        store,
-        ownerId: "scheduler-a",
+        ownerId: "outbox-a",
     });
+
+const runner =
+    dispatcher.start();
 ```
 
-A typical application may configure its Redis client with:
+Event type `order.created` is handed off to queue name `event.order.created`.
 
-```dotenv
-REDIS_URL=redis://localhost:6379
-```
+The outbox dispatcher supports leases, stale recovery, retry/backoff, custom publishers, a local EventBus, cleanup and statistics.
 
-BCP does not read `REDIS_URL` automatically. Redis credentials, TLS/Cluster/Sentinel configuration and connection lifecycle stay application-owned.
+`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.
 
-`bcp/jobs` is server-only and must not be imported into page/client bundles.
+## Storage providers
 
-## Application Packaging — 0.2.4+
+Supported presets are Local Server, Amazon S3 and Cloudflare R2. Storage credentials are server-only and must not use `BCP_PUBLIC_*` variables.
 
-Generated projects include:
+## 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.10.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.10",
+  "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,97 +82,109 @@ const worker =
     });
 ```
 
-Retry-exhausted jobs are available through the adapter DLQ contract:
+## Workflow orchestration — BCP 0.2.11+
 
 ```ts
-const deadLetters =
-    await jobs.deadLetters();
+import {
+    createWorkflow,
+} from "bcp/workflow";
 
-await jobs.requeueDeadLetter(
-    deadLetters[0].id,
-    {
-        resetAttempts: true,
-    }
-);
+export const onboarding =
+    createWorkflow(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
 ```
 
-Operational helpers:
+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
-await jobs.recoverStale();
-const stats = await jobs.stats();
-await jobs.cleanup({
-    before:
-        Date.now() -
-        7 * 24 * 60 * 60 * 1000,
-});
-```
+import {
+    db,
+} from "bcp/database";
+
+import {
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
+
+const outboxStore =
+    createSqlOutboxStore({
+        database: db,
+        driver: "mysql",
+    });
 
-### Redis-compatible adapters
+const outbox =
+    createTransactionalOutbox({
+        store: outboxStore,
+    });
 
-BCP does not install a Redis library. Supply an application-owned command client:
+await db.transaction(
+    async tx => {
+        await tx.execute(
+            "INSERT INTO orders ..."
+        );
 
-```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
+        await outbox.publish(
+            tx,
+            "order.created",
+            {
+                orderId: 42,
+            }
+        );
+    }
+);
 ```
 
-Create a durable queue:
+Generate the required table SQL:
 
 ```ts
 import {
-    createJobQueue,
-    createRedisJobQueueAdapter,
-} from "bcp/jobs";
-
-const adapter =
-    createRedisJobQueueAdapter({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
+    createOutboxMigrationSql,
+} from "bcp/events";
 
-export const jobs =
-    createJobQueue({
-        adapter,
-    });
+const sql =
+    createOutboxMigrationSql(
+        "mysql"
+    );
 ```
 
-Create a shared schedule store:
+Dispatch committed events to the durable queue:
 
 ```ts
 import {
-    createJobScheduler,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
+    createOutboxDispatcher,
+} from "bcp/events";
 
-const store =
-    createRedisJobScheduleStore({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
-
-export const scheduler =
-    createJobScheduler({
+const dispatcher =
+    createOutboxDispatcher({
+        store: outboxStore,
         queue: jobs,
-        store,
-        ownerId: "scheduler-a",
+        ownerId: "outbox-a",
     });
-```
-
-A typical deployment may use:
 
-```dotenv
-REDIS_URL=redis://localhost:6379
+const runner =
+    dispatcher.start();
 ```
 
-BCP does not read this variable automatically. The application owns Redis connection creation, credentials, TLS/Cluster configuration and shutdown.
+Event `order.created` is queued as `event.order.created`.
 
-The processing model is at-least-once, so side-effecting job handlers should be idempotent when duplicate execution is unsafe.
+The dispatcher supports leases, stale recovery, retry/backoff, custom publishers, local EventBus delivery, retention cleanup and statistics.
 
-`bcp/jobs` 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
 
@@ -225,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
@@ -252,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
@@ -261,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.