create-bcp-app 0.2.9 → 0.2.11

package/README.md

@@ -92,10 +92,10 @@ Example:
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.9",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.11",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.9"
+    "version": "0.2.11"
   },
   "packageManager": "npm",
   "presets": {
@@ -107,9 +107,7 @@ Example:
 }
 ```
 
-This manifest records scaffold identity only. It is intended for framework diagnostics, update/migration tooling and project-aware documentation. It must not contain secrets.
-
-The file should normally be committed to source control.
+This manifest records scaffold identity only. It must not contain secrets and should normally be committed to source control.
 
 ## Generated application defaults
 
@@ -157,24 +155,6 @@ The database choice adds starter configuration and the matching driver:
 
 For **MySQL**, **PostgreSQL** and **SQLite**, generated `lib/database.ts` exposes framework database primitives through `bcp/database`.
 
-Generated examples:
-
-```dotenv
-DB_HOST=localhost
-DB_PORT=3306
-DB_USER=
-DB_PASSWORD=
-DB_NAME=bcp_app
-```
-
-```dotenv
-DATABASE_URL=postgresql://postgres:password@localhost:5432/bcp_app
-```
-
-```dotenv
-DATABASE_URL=./data/bcp.sqlite
-```
-
 The generator intentionally does not force an ORM.
 
 ## Storage providers
@@ -193,16 +173,7 @@ BCP_SESSION_SECRET=
 
 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:
-
-```ts
-import {
-    createAuth,
-    createMemoryAuthSessionStore,
-} from "bcp/auth";
-```
-
-The memory store is intended for development/tests. Multi-process production deployments should implement `AuthSessionStore` using shared durable storage.
+BCP `0.2.5+` can opt into revocable server-side auth state through `AuthSessionStore`.
 
 ## Authorization & request security — 0.2.6+
 
@@ -226,7 +197,7 @@ import {
 
 ## Background jobs — 0.2.8+
 
-Generated projects can create a server-only background job queue without adding another package:
+Generated projects can create a server-only background job queue:
 
 ```ts
 import {
@@ -237,7 +208,7 @@ export const jobs =
     createJobQueue();
 ```
 
-Workers support concurrency, delayed jobs, retry/backoff and cancellation. The default memory adapter is process-local and should be replaced with a durable `JobQueueAdapter` for production workloads that must survive restarts or coordinate across instances.
+Workers support concurrency, delayed jobs, retry/backoff and cancellation.
 
 ## Job scheduling — 0.2.9+
 
@@ -278,20 +249,102 @@ await scheduler.schedule(
 );
 ```
 
-Start the scheduler loop:
+## 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 runner =
-    scheduler.start({
-        pollIntervalMs: 1_000,
-        leaseMs: 30_000,
+const worker =
+    jobs.startWorker({
+        workerId: "worker-a",
+        concurrency: 4,
+        visibilityTimeoutMs: 30_000,
+        heartbeatIntervalMs: 10_000,
     });
 ```
 
-The default schedule store is process-local. Multi-instance production deployments should implement a shared durable `JobScheduleStore`; its `acquireDue()` operation must atomically lease due schedules. A durable scheduler deployment normally also uses a shared durable `JobQueueAdapter`.
+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.
 
+## 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;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+
+            workflow.parallel(
+                "initialize",
+                parallel => {
+                    parallel.step(
+                        "preferences",
+                        createPreferences
+                    );
+                    parallel.step(
+                        "workspace",
+                        createWorkspace
+                    );
+                }
+            );
+
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
+```
+
+Step-level retry and compensation are supported:
+
+```ts
+workflow.step(
+    "reserve-stock",
+    reserveStock,
+    {
+        maxAttempts: 3,
+        retryDelayMs: 1_000,
+        compensate:
+            releaseStock,
+    }
+);
+```
+
+For durable queue-backed execution, pass an existing `BackgroundJobQueue` and a durable shared `WorkflowStore`:
+
+```ts
+const fulfillment =
+    createWorkflow(
+        "order.fulfillment",
+        defineWorkflow,
+        {
+            queue: jobs,
+            store:
+                workflowStore,
+        }
+    );
+```
+
+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.
+
+External side effects should remain idempotent because durable queue execution is at-least-once.
+
+`bcp/workflow` is server-only and cannot be imported into page/client bundles.
+
 ## Application Packaging — 0.2.4+
 
 Generated projects include:
@@ -337,5 +390,5 @@ bcp generate migration create_users
 The `--bcp` option is mainly for prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.9.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.11.tgz
 ```

package/package.json

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

package/template/README.md

@@ -25,17 +25,11 @@ npm start
 npm run update
 ```
 
-The generated scripts call commands such as `bcp dev`, `bcp generate`, `bcp build`, `bcp package` and `bcp start`. npm automatically adds the project's `node_modules/.bin` directory to `PATH` while an npm script is running.
+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:
-
-```text
-bcp.project.json
-```
-
-It records non-secret scaffold choices such as Tailwind, database, authentication and storage presets so BCP diagnostics/tooling can understand the project without guessing configuration from source files.
+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.
 
@@ -45,8 +39,6 @@ Projects created with the `JWT Cookie` preset remain stateless by default and us
 
 BCP Authentication Platform v2 can opt into revocable server-side session state with `createAuth()` and `AuthSessionStore`.
 
-The memory store is intended for local development/tests. Use a shared durable `AuthSessionStore` implementation for multi-process or multi-container production deployments.
-
 ## Authorization & request security — BCP 0.2.6+
 
 Use permission guards and resource policies from `bcp/auth`, and same-origin/CSRF protection from `bcp/server`.
@@ -55,8 +47,6 @@ Authorization must always be enforced server-side. Client UI visibility is not a
 
 ## Observability — BCP 0.2.7+
 
-Create process-local metrics and health/readiness registries:
-
 ```ts
 import {
     createHealthRegistry,
@@ -95,14 +85,8 @@ jobs.register<{
 );
 ```
 
-Workers support delayed jobs, retry/backoff, cancellation and configurable concurrency.
-
-The default memory adapter is process-local and not durable. For production jobs that must survive restarts or run across multiple processes/containers, implement `JobQueueAdapter` with shared durable infrastructure.
-
 ## Job scheduling — BCP 0.2.9+
 
-Add recurring schedules on top of the same queue:
-
 ```ts
 import {
     createJobScheduler,
@@ -114,50 +98,203 @@ export const scheduler =
     });
 ```
 
-Interval schedule:
+Example UTC cron schedule:
 
 ```ts
 await scheduler.schedule(
-    "cache.cleanup",
+    "report.weekday",
     {},
     {
-        everyMs: 300_000,
+        cron: "30 9 * * 1-5",
     }
 );
 ```
 
-UTC cron schedule:
+## Durable jobs — BCP 0.2.10+
+
+Workers can use visibility leases, heartbeat renewal and stale-running recovery:
 
 ```ts
-await scheduler.schedule(
-    "report.weekday",
-    {},
+const worker =
+    jobs.startWorker({
+        workerId: "worker-a",
+        concurrency: 4,
+        visibilityTimeoutMs: 30_000,
+        heartbeatIntervalMs: 10_000,
+    });
+```
+
+Retry-exhausted jobs are available through the adapter DLQ contract:
+
+```ts
+const deadLetters =
+    await jobs.deadLetters();
+
+await jobs.requeueDeadLetter(
+    deadLetters[0].id,
     {
-        cron: "30 9 * * 1-5",
+        resetAttempts: true,
     }
 );
 ```
 
-Start and stop the scheduler lifecycle:
+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
-const schedulerRunner =
-    scheduler.start({
-        pollIntervalMs: 1_000,
-        leaseMs: 30_000,
+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}",
     });
 
-await schedulerRunner.stop();
-await scheduler.close();
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+        store,
+        ownerId: "scheduler-a",
+    });
+```
+
+A typical deployment may use:
+
+```dotenv
+REDIS_URL=redis://localhost:6379
 ```
 
-The default `createMemoryJobScheduleStore()` is process-local. Multi-instance production deployments should implement a shared durable `JobScheduleStore` whose `acquireDue()` atomically leases due schedules. Durable deployments normally also use a shared `JobQueueAdapter`.
+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.
 
-## Generate framework files
+## 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;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+
+            workflow.parallel(
+                "initialize",
+                parallel => {
+                    parallel.step(
+                        "preferences",
+                        createPreferences
+                    );
+                    parallel.step(
+                        "workspace",
+                        createWorkspace
+                    );
+                }
+            );
+
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
+```
+
+Step retry and compensation:
+
+```ts
+workflow.step(
+    "reserve-stock",
+    reserveStock,
+    {
+        maxAttempts: 3,
+        retryDelayMs: 1_000,
+        compensate:
+            releaseStock,
+    }
+);
+```
+
+For queue-backed execution:
+
+```ts
+const fulfillment =
+    createWorkflow(
+        "order.fulfillment",
+        defineWorkflow,
+        {
+            queue: jobs,
+            store:
+                workflowStore,
+        }
+    );
+```
+
+The default `createMemoryWorkflowStore()` is for local development/tests. Multi-instance production deployments should implement a shared durable `WorkflowStore` with atomic `claim()` behavior.
 
-BCP can generate common project files:
+Workflow handlers that perform external side effects should be idempotent because durable job execution is at-least-once.
+
+`bcp/workflow` is server-only and cannot be imported into page/client bundles.
+
+## Generate framework files
 
 ```bash
 npm run generate -- page dashboard/users
@@ -166,7 +303,7 @@ npm run generate -- middleware
 npm run generate -- migration create_users
 ```
 
-Equivalent direct BCP CLI commands are:
+Equivalent direct commands:
 
 ```bash
 bcp generate page dashboard/users
@@ -177,23 +314,16 @@ bcp generate migration create_users
 
 Existing page/API/middleware targets are not replaced unless `--force` is supplied explicitly.
 
-After generating routes, inspect them with:
-
-```bash
-npm run routes
-```
-
 ## Direct CLI usage
 
-BCP Framework is installed as a project-local dependency. It is not installed globally by `create-bcp-app`.
+BCP Framework is installed as a project-local dependency.
 
-PowerShell does not automatically add `node_modules/.bin` to its normal command search path, so use `npm exec` for direct commands:
+For PowerShell direct usage:
 
 ```powershell
 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
@@ -202,31 +332,15 @@ 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.
 
-## Project diagnostics
-
-```powershell
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect
-```
-
 ## Production build
 
-Create the raw standalone production build:
-
 ```bash
 npm run build
-```
-
-Start it with:
-
-```bash
 npm start
 ```
 
 ## Deployment package — BCP 0.2.4+
 
-Create a fresh production build and deployment-oriented package:
-
 ```bash
 npm run package
 ```