create-bcp-app 0.2.7 → 0.2.9

package/README.md

@@ -92,10 +92,10 @@ Example:
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.7",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.9",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.7"
+    "version": "0.2.9"
   },
   "packageManager": "npm",
   "presets": {
@@ -133,14 +133,7 @@ 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
-- starter utility classes
+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:
 
@@ -162,9 +155,9 @@ 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 the framework database primitives through `bcp/database`. Provider connections are managed behind Database Platform v2 instead of being created directly in generated application code.
+For **MySQL**, **PostgreSQL** and **SQLite**, generated `lib/database.ts` exposes framework database primitives through `bcp/database`.
 
-Generated MySQL environment variables:
+Generated examples:
 
 ```dotenv
 DB_HOST=localhost
@@ -174,100 +167,25 @@ DB_PASSWORD=
 DB_NAME=bcp_app
 ```
 
-Generated PostgreSQL environment variable:
-
 ```dotenv
 DATABASE_URL=postgresql://postgres:password@localhost:5432/bcp_app
 ```
 
-Generated SQLite environment variable:
-
 ```dotenv
 DATABASE_URL=./data/bcp.sqlite
 ```
 
-`bcp/database` infers PostgreSQL from `postgres://` or `postgresql://` connection URLs. SQLite is inferred from `:memory:`, `sqlite:` / `file:` locations and common `.sqlite`, `.sqlite3` or `.db` file paths. Applications may also configure `DB_DRIVER` explicitly.
-
-Placeholder syntax follows the selected provider:
-
-```text
-MySQL       ?
-SQLite      ?
-PostgreSQL  $1, $2, ...
-```
-
 The generator intentionally does not force an ORM.
 
 ## Storage providers
 
-Selecting a storage provider creates `lib/storage.ts` and adds provider-specific environment settings.
-
-### Local Server
-
-```bash
-npx create-bcp-app my-app --storage local
-```
-
-Environment:
-
-```dotenv
-STORAGE_LOCAL_DIRECTORY=./storage
-```
-
-The generated helper uses `createLocalStorage()`.
-
-### Amazon S3
-
-```bash
-npx create-bcp-app my-app --storage amazon-s3
-```
-
-Generated environment settings:
-
-```dotenv
-AWS_S3_BUCKET=
-AWS_REGION=ap-southeast-1
-AWS_ACCESS_KEY_ID=
-AWS_SECRET_ACCESS_KEY=
-AWS_SESSION_TOKEN=
-AWS_S3_PREFIX=
-```
-
-The helper uses `createS3Storage()`. Explicit credentials can remain unset when deployment uses the AWS SDK server-side credential chain, such as an IAM role.
-
-### Cloudflare R2
-
-```bash
-npx create-bcp-app my-app --storage cloudflare-r2
-```
-
-Generated environment settings:
-
-```dotenv
-R2_ACCOUNT_ID=
-R2_BUCKET=
-R2_ACCESS_KEY_ID=
-R2_SECRET_ACCESS_KEY=
-R2_PREFIX=
-```
+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:
-
-```text
-lib/
-└─ auth.ts
-
-app/api/auth/
-├─ login/route.ts
-├─ logout/route.ts
-└─ me/route.ts
-```
-
-and adds:
+Selecting `JWT Cookie` creates `lib/auth.ts` and starter `/api/auth/login`, `/logout` and `/me` routes, and adds:
 
 ```dotenv
 BCP_SESSION_SECRET=
@@ -275,87 +193,104 @@ BCP_SESSION_SECRET=
 
 Set this to a cryptographically random secret of at least 32 bytes before real authentication use.
 
-The generated `authenticateCredentials(email, password)` returns `null` until the application connects it to its own user store and password-hash verification.
-
-Generated auth stays in backward-compatible stateless JWT-cookie mode by default.
-
-BCP `0.2.5+` can opt into revocable server-side auth state without changing the generated auth route structure:
+BCP `0.2.5+` can opt into revocable server-side auth state:
 
 ```ts
 import {
     createAuth,
     createMemoryAuthSessionStore,
 } from "bcp/auth";
-
-const sessionStore =
-    createMemoryAuthSessionStore();
-
-const frameworkAuth =
-    createAuth<AuthenticatedUser>({
-        store: sessionStore,
-        idleTimeout: 60 * 30,
-    });
 ```
 
 The memory store is intended for development/tests. Multi-process production deployments should implement `AuthSessionStore` using shared durable storage.
 
 ## Authorization & request security — 0.2.6+
 
-Generated applications can add permissions to their application user shape and use server-side permission guards without changing the auth preset routes:
+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:
 
 ```ts
 import {
-    createPermissionGuard,
-    hasPermission,
-} from "bcp/auth";
+    createHealthRegistry,
+    createMetricsRegistry,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
 ```
 
-For resource-specific decisions, use `defineAuthorizationPolicy()`, `can()` or `authorize()`.
+`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+
 
-Cookie-authenticated mutation routes can opt into same-origin and CSRF protection through `bcp/server`:
+Generated projects can create a server-only background job queue without adding another package:
 
 ```ts
 import {
-    createCsrfToken,
-    requireCsrfRequest,
-    requireSameOriginRequest,
-} from "bcp/server";
-```
+    createJobQueue,
+} from "bcp/jobs";
 
-`createCsrfToken()` uses `BCP_CSRF_SECRET` when configured and otherwise falls back to `BCP_SESSION_SECRET`, so the generated JWT auth preset does not require another environment variable to get started. Production applications may define a separate `BCP_CSRF_SECRET` for independent key rotation.
+export const jobs =
+    createJobQueue();
+```
 
-Authorization and CSRF checks must remain on the server; hiding UI controls in client code is not an authorization boundary.
+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.
 
-## Observability — 0.2.7+
+## Job scheduling — 0.2.9+
 
-Generated projects can opt into process-local metrics and health/readiness without adding another dependency:
+Recurring schedules use the same `bcp/jobs` entrypoint:
 
 ```ts
 import {
-    createHealthRegistry,
-    createMetricsRegistry,
-    createRequestMetricsMiddleware,
-} from "bcp/observability";
+    createJobScheduler,
+} from "bcp/jobs";
+
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+    });
+```
+
+Interval schedule:
 
-export const metrics =
-    createMetricsRegistry();
+```ts
+await scheduler.schedule(
+    "cache.cleanup",
+    {},
+    {
+        everyMs: 300_000,
+    }
+);
+```
 
-export const health =
-    createHealthRegistry();
+UTC cron schedule:
 
-export const requestMetrics =
-    createRequestMetricsMiddleware(
-        metrics
-    );
+```ts
+await scheduler.schedule(
+    "report.weekday",
+    {},
+    {
+        cron: "30 9 * * 1-5",
+    }
+);
 ```
 
-Expose metrics from an application API route with `createMetricsResponse(metrics)`. The response uses Prometheus-compatible text format.
+Start the scheduler loop:
 
-Health endpoints can return `health.response()`, which uses HTTP `200` when all checks pass and `503` when any dependency check fails or times out.
+```ts
+const runner =
+    scheduler.start({
+        pollIntervalMs: 1_000,
+        leaseMs: 30_000,
+    });
+```
 
-The default HTTP request metrics use `method` and `status` labels only. Raw paths are intentionally excluded to avoid high-cardinality metric series.
+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/observability` is server-only. Protect metrics and operational health detail with an appropriate network or authorization boundary when needed.
+`bcp/jobs` is server-only and must not be imported into page/client bundles.
 
 ## Application Packaging — 0.2.4+
 
@@ -365,32 +300,8 @@ Generated projects include:
 npm run package
 ```
 
-This runs the BCP `standalone-node` application packaging flow and writes:
-
-```text
-.bcp-framework/package/
-├─ client/
-├─ server/
-├─ public/                 # when present
-├─ package.json
-├─ package-lock.json       # when a safe production lock can be derived
-├─ bcp.package.json
-├─ bcp.deployment.json
-├─ bcp.env.json
-├─ Dockerfile
-└─ README.md
-```
-
 The deployment package excludes application `devDependencies` and project `.env` values. Supply real secrets through the deployment environment.
 
-For a package with a generated production lockfile:
-
-```bash
-cd .bcp-framework/package
-npm ci --omit=dev
-npm start
-```
-
 ## Project generators after creation
 
 ```bash
@@ -418,25 +329,13 @@ bcp generate migration create_users
 --database <database>     none | mysql | postgresql | sqlite | mongodb
 --auth <preset>           none | jwt-cookie
 --storage <provider>      none | local | amazon-s3 | cloudflare-r2
--y, --yes                 Accept defaults (Tailwind enabled, no database, no auth, no storage)
+-y, --yes                 Accept defaults
 --bcp <specifier>         Override dependencies.bcp
 -h, --help                Show help
 ```
 
-Examples:
-
-```bash
-npx create-bcp-app my-app --tailwind --database mysql --auth jwt-cookie --storage local
-npx create-bcp-app my-app --database postgresql
-npx create-bcp-app my-app --database sqlite
-npx create-bcp-app my-app --storage amazon-s3
-npx create-bcp-app my-app --storage cloudflare-r2
-npx create-bcp-app my-app --no-tailwind --database mongodb
-npx create-bcp-app my-app --yes
-```
-
 The `--bcp` option is mainly for prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.7.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.9.tgz
 ```

package/package.json

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

package/template/README.md

@@ -43,87 +43,117 @@ Commit this file with the project. Do not put passwords, access keys, session se
 
 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:
+BCP Authentication Platform v2 can opt into revocable server-side session state with `createAuth()` and `AuthSessionStore`.
 
-```ts
-import {
-    createAuth,
-    createMemoryAuthSessionStore,
-} from "bcp/auth";
+The memory store is intended for local development/tests. Use a shared durable `AuthSessionStore` implementation for multi-process or multi-container production deployments.
 
-const sessionStore =
-    createMemoryAuthSessionStore();
+## Authorization & request security — BCP 0.2.6+
 
-export const appAuth =
-    createAuth({
-        store: sessionStore,
-        idleTimeout: 60 * 30,
-    });
-```
+Use permission guards and resource policies from `bcp/auth`, and same-origin/CSRF protection from `bcp/server`.
 
-The memory store is intended for local development/tests. Use a shared durable `AuthSessionStore` implementation for multi-process or multi-container production deployments.
+Authorization must always be enforced server-side. Client UI visibility is not a security boundary.
 
-## Authorization & request security — BCP 0.2.6+
+## Observability — BCP 0.2.7+
 
-Server-side permission guards:
+Create process-local metrics and health/readiness registries:
 
 ```ts
 import {
-    createPermissionGuard,
-} from "bcp/auth";
-
-export const guard =
-    createPermissionGuard(
-        "dashboard.read"
-    );
+    createHealthRegistry,
+    createMetricsRegistry,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
 ```
 
-For ownership or resource-specific rules, use `defineAuthorizationPolicy()`, `can()` and `authorize()` from `bcp/auth`.
+Protect operational endpoints when their contents should not be public.
+
+## Background jobs — BCP 0.2.8+
 
-Cookie-authenticated mutation routes can validate browser origin and CSRF state:
+Create a server-only background queue:
 
 ```ts
 import {
-    createCsrfToken,
-    requireCsrfRequest,
-    requireSameOriginRequest,
-} from "bcp/server";
+    createJobQueue,
+} from "bcp/jobs";
+
+export const jobs =
+    createJobQueue();
 ```
 
-`createCsrfToken()` uses `BCP_CSRF_SECRET` when configured and otherwise falls back to `BCP_SESSION_SECRET`.
+Register typed work:
 
-Authorization must always be enforced server-side. Client UI visibility is not a security boundary.
+```ts
+jobs.register<{
+    userId: number;
+}>(
+    "email.welcome",
+    async ({ payload }) => {
+        await sendWelcomeEmail(
+            payload.userId
+        );
+    }
+);
+```
 
-## Observability — BCP 0.2.7+
+Workers support delayed jobs, retry/backoff, cancellation and configurable concurrency.
 
-Create process-local metrics and health/readiness registries:
+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 {
-    createHealthRegistry,
-    createMetricsRegistry,
-    createRequestMetricsMiddleware,
-} from "bcp/observability";
+    createJobScheduler,
+} from "bcp/jobs";
 
-export const metrics =
-    createMetricsRegistry();
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+    });
+```
 
-export const health =
-    createHealthRegistry();
+Interval schedule:
 
-export const requestMetrics =
-    createRequestMetricsMiddleware(
-        metrics
-    );
+```ts
+await scheduler.schedule(
+    "cache.cleanup",
+    {},
+    {
+        everyMs: 300_000,
+    }
+);
 ```
 
-Expose Prometheus-compatible metrics with `createMetricsResponse(metrics)` from a server API route.
+UTC cron schedule:
 
-Use `health.response()` for readiness endpoints. It returns HTTP `200` when all checks pass and `503` when a check fails or times out.
+```ts
+await scheduler.schedule(
+    "report.weekday",
+    {},
+    {
+        cron: "30 9 * * 1-5",
+    }
+);
+```
 
-The default request metrics use bounded `method` and `status` labels and do not include raw paths.
+Start and stop the scheduler lifecycle:
 
-Protect operational endpoints when their contents should not be public.
+```ts
+const schedulerRunner =
+    scheduler.start({
+        pollIntervalMs: 1_000,
+        leaseMs: 30_000,
+    });
+
+await schedulerRunner.stop();
+await scheduler.close();
+```
+
+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/jobs` is server-only and cannot be imported into page/client bundles.
 
 ## Generate framework files
 
@@ -170,39 +200,15 @@ npm exec -- bcp-framework build
 npm exec -- bcp-framework package
 ```
 
-You can also execute the Windows command shim explicitly:
-
-```powershell
-.\node_modules\.bin\bcp-framework.cmd --version
-```
-
 Microsoft SQL Server can install another Windows executable named `bcp.exe`, so the `bcp-framework` alias avoids that command-name collision.
 
-Use this convention:
-
-```text
-Inside npm scripts      -> bcp ...
-Direct PowerShell usage -> npm exec -- bcp-framework ...
-```
-
 ## Project diagnostics
 
-Run:
-
 ```powershell
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect
 ```
 
-Machine-readable reports:
-
-```powershell
-npm exec -- bcp-framework doctor --json
-npm exec -- bcp-framework inspect --json
-```
-
-Doctor checks common project/runtime problems while Inspect shows the resolved configuration, routes, dependencies and project metadata BCP sees.
-
 ## Production build
 
 Create the raw standalone production build:
@@ -217,8 +223,6 @@ Start it with:
 npm start
 ```
 
-The production build is written to `.bcp-framework/build` and runs as a standalone Node.js server.
-
 ## Deployment package — BCP 0.2.4+
 
 Create a fresh production build and deployment-oriented package:
@@ -227,22 +231,6 @@ Create a fresh production build and deployment-oriented package:
 npm run package
 ```
 
-The output is written to:
-
-```text
-.bcp-framework/package/
-```
-
-It contains the standalone client/server output, a production-only dependency manifest, deployment/environment metadata, file integrity hashes and a starter Dockerfile.
+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.
-
-For a package with a generated production lockfile:
-
-```bash
-cd .bcp-framework/package
-npm ci --omit=dev
-npm start
-```
-
-If `bcp.package.json` reports that no lockfile was included, use the install command recorded in that manifest instead.