create-bcp-app 0.2.19 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ npm run dev
 
 ## Project-local BCP CLI
 
-`create-bcp-app` installs BCP Framework as a project-local dependency. Generated npm scripts use the local CLI:
+Generated npm scripts use the project-local framework CLI:
 
 ```json
 {
@@ -64,17 +64,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.2.19` target:
+Example for the `0.3.0` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.19",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.3.0",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.19"
+    "version": "0.3.0"
   },
   "packageManager": "npm",
   "presets": {
@@ -88,6 +88,59 @@ Example for the `0.2.19` target:
 
 This manifest records scaffold identity only. Do not place secrets in it.
 
+## BCP Application Platform — 0.3.0+
+
+Applications can optionally centralize server infrastructure through `bcp/application`:
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "my-app",
+    });
+```
+
+Register existing provider-native services:
+
+```ts
+app.provide(
+    "database",
+    database
+);
+
+app.provide(
+    "cache",
+    cache
+);
+```
+
+Register long-running lifecycle resources:
+
+```ts
+app.addResource({
+    name: "database",
+
+    start() {
+        return database.connect();
+    },
+
+    ready() {
+        return database.ready;
+    },
+
+    stop() {
+        return database.close();
+    },
+});
+```
+
+Application startup orders plugins before infrastructure resources and the application start hook. Shutdown reverses dependency order.
+
+Existing `bcp/database`, `bcp/jobs`, `bcp/workflow`, `bcp/events`, `bcp/realtime`, `bcp/cache`, `bcp/plugins`, `bcp/observability` and `bcp/deployment` APIs remain usable independently.
+
 ## Database presets
 
 Database choices add starter configuration and the matching driver:
@@ -137,7 +190,7 @@ BCP does not install a WebSocket server library. Applications adapt their provid
 
 ## Plugins
 
-`bcp/plugins` provides dependency ordering, module composition, lifecycle hooks, config parsing, shared services and async hooks.
+`bcp/plugins` provides dependency ordering, module composition, lifecycle hooks, config parsing, shared services and async hooks. Plugin definitions/modules can be passed directly to `createApp()`.
 
 ## Cache Platform v2
 
@@ -165,104 +218,11 @@ export const tracer =
     });
 ```
 
-Tracing supports W3C `traceparent`, correlation IDs, request middleware, explicit carriers for jobs/workflows/events/realtime and provider-neutral exporters.
-
-## Deployment Platform v2 — 0.2.18+
-
-Use `bcp/deployment` to coordinate application resources in production:
-
-```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
-
-export const deployment =
-    createDeploymentRuntime({
-        serviceName: "my-app",
-    });
-```
-
-Register shared dependencies before components that use them:
-
-```ts
-deployment.addResource({
-    name: "database",
-
-    async start() {
-        await db.connect();
-    },
-
-    ready() {
-        return db.status === "ready";
-    },
-
-    async stop() {
-        await db.close();
-    },
-});
-
-deployment.addResource({
-    name: "workers",
-
-    start() {
-        worker = jobs.startWorker();
-    },
-
-    async stop() {
-        await worker.stop();
-    },
-});
-
-await deployment.start();
-```
-
-Startup follows registration order and shutdown reverses it. This naturally stops workers before database/cache/Redis connections.
-
-Readiness endpoint:
-
-```ts
-import {
-    createDeploymentReadinessResponse,
-} from "bcp/deployment";
-
-export function GET() {
-    return createDeploymentReadinessResponse(
-        deployment
-    );
-}
-```
-
-Runtime identity can use:
-
-```text
-BCP_DEPLOYMENT_ID
-BCP_INSTANCE_ID
-BCP_RELEASE
-NODE_ENV
-BCP_SHUTDOWN_TIMEOUT_MS
-```
-
-Install graceful signal handling with:
-
-```ts
-const removeSignals =
-    deployment.installSignalHandlers();
-```
-
-Default signals are `SIGTERM` and `SIGINT`.
+Tracing supports W3C `traceparent`, correlation IDs, request middleware, explicit carriers and provider-neutral exporters.
 
-## Stability & API Freeze — 0.2.19
-
-`0.2.19` keeps the `0.2.x` public package surface stable before the next platform baseline.
-
-Framework maintainers can validate the frozen contract with:
-
-```bash
-npm run api:check
-npm run release:readiness
-```
+## Deployment Platform v2
 
-Generated applications do not need to run these framework-repository release commands. Application code should continue importing documented `bcp/*` entrypoints rather than private framework source paths.
+`bcp/deployment` remains available for applications that want to own resource lifecycle directly. `bcp/application` reuses the same resource/readiness/diagnostics model when using the Application Platform.
 
 ## Application packaging
 
@@ -273,7 +233,7 @@ npm run package
 
 The deployment package excludes application `devDependencies` and project `.env` values. Supply secrets through the deployment environment.
 
-BCP `0.2.19` prepared framework packages preserve the compiled ESM runtime map introduced by Deployment Platform v2 for the main server entrypoints including config, auth, observability, deployment, server and middleware.
+BCP `0.3.0` prepared framework packages add compiled `application.mjs` to the compiled ESM server-runtime set.
 
 ## Project generators
 
@@ -301,5 +261,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.19.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.3.0.tgz
 ```

package/package.json

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

package/template/README.md

@@ -27,6 +27,56 @@ npm run update
 
 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.
 
+## Application Platform — BCP 0.3.0+
+
+For applications with several server subsystems, `bcp/application` provides one optional composition root:
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "bcp-app",
+    });
+```
+
+Register shared service instances before startup:
+
+```ts
+app.provide("database", database);
+app.provide("cache", cache);
+```
+
+Register lifecycle-owned resources:
+
+```ts
+app.addResource({
+    name: "database",
+
+    start() {
+        return database.connect();
+    },
+
+    ready() {
+        return database.ready;
+    },
+
+    stop() {
+        return database.close();
+    },
+});
+```
+
+Then start the application runtime from your server/bootstrap composition code:
+
+```ts
+await app.start();
+```
+
+Existing plugin modules can be passed directly to `createApp()`. Existing subsystem APIs remain available independently when a centralized application runtime is unnecessary.
+
 ## Authentication and authorization
 
 JWT Cookie projects can use `createAuth()` and optional `AuthSessionStore` revocation. Permission guards/resource policies live in `bcp/auth`; same-origin/CSRF helpers live in `bcp/server`.
@@ -72,7 +122,7 @@ BCP does not install a WebSocket server library. Adapt the selected provider thr
 
 ## Plugins
 
-`bcp/plugins` provides reusable server-side plugins/modules, dependency ordering, lifecycle hooks, config parsing, shared services and awaited hooks.
+`bcp/plugins` provides reusable server-side plugins/modules, dependency ordering, lifecycle hooks, config parsing, shared services and awaited hooks. Plugin definitions/modules can also be composed by `bcp/application`.
 
 ## Cache Platform v2
 
@@ -102,87 +152,24 @@ export const tracer =
 
 Tracing supports AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers and provider-neutral exporters.
 
-## Deployment Platform v2 — BCP 0.2.18+
-
-Use `bcp/deployment` to manage production resource lifecycle:
-
-```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
-
-export const deployment =
-    createDeploymentRuntime({
-        serviceName: "bcp-app",
-    });
-```
-
-Register dependencies first:
-
-```ts
-deployment.addResource({
-    name: "database",
-
-    async start() {
-        await db.connect();
-    },
-
-    ready() {
-        return db.status === "ready";
-    },
-
-    async stop() {
-        await db.close();
-    },
-});
-```
-
-Register workers/realtime services afterward so reverse-order shutdown stops them before their shared database/cache/Redis dependencies.
-
-Start runtime:
-
-```ts
-await deployment.start();
-```
-
-Readiness endpoint:
-
-```ts
-import {
-    createDeploymentReadinessResponse,
-} from "bcp/deployment";
-
-export function GET() {
-    return createDeploymentReadinessResponse(
-        deployment
-    );
-}
-```
-
-Install graceful signal handling when the app owns process signals:
-
-```ts
-const removeSignals =
-    deployment.installSignalHandlers();
-```
+## Deployment lifecycle
 
-Default signals are `SIGTERM` and `SIGINT`.
+`bcp/deployment` remains available when the project wants direct lifecycle ownership. `bcp/application` reuses the same resource/readiness/diagnostics model and adds application/plugin composition around it.
 
-Deployment identity can be supplied through:
+Application Platform startup order is:
 
 ```text
-BCP_DEPLOYMENT_ID
-BCP_INSTANCE_ID
-BCP_RELEASE
-NODE_ENV
-BCP_SHUTDOWN_TIMEOUT_MS
+application setup
+plugins
+resources
+application start
 ```
 
-## Stability baseline — BCP 0.2.19
+Shutdown reverses resource dependencies before disposing the application.
 
-BCP `0.2.19` freezes the documented `0.2.x` public `bcp/*` entrypoints and prepared package-resolution contract before the next `0.3.0` baseline.
+## API baseline
 
-Application code should import documented public entrypoints and avoid private framework `packages/*` paths. This keeps applications compatible with the frozen `0.2.19` surface.
+BCP `0.3.0` preserves the public `0.2.19` entrypoints and adds `bcp/application`. Application code should import documented public `bcp/*` entrypoints and avoid private framework `packages/*` paths.
 
 ## Production build
 
@@ -199,7 +186,7 @@ npm run package
 
 BCP excludes project `.env` files and application `devDependencies` from the deployment package. Supply secrets through the deployment environment.
 
-BCP 0.2.19 preserves compiled `.mjs` runtimes for the main server entrypoints, including config, auth, observability, deployment, server and middleware.
+BCP 0.3.0 adds compiled `application.mjs` to the main compiled server-runtime entrypoints.
 
 ## Direct CLI usage