create-bcp-app 0.2.19 → 0.3.1

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 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.1` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.19",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.3.1",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.19"
+    "version": "0.3.1"
   },
   "packageManager": "npm",
   "presets": {
@@ -88,181 +88,164 @@ Example for the `0.2.19` target:
 
 This manifest records scaffold identity only. Do not place secrets in it.
 
-## Database presets
-
-Database choices add starter configuration and the matching driver:
-
-- MySQL: `mysql2`
-- PostgreSQL: `pg`
-- SQLite: `better-sqlite3`
-- MongoDB: `mongodb`
-- None: no database dependency
+## Application Platform
 
-For MySQL, PostgreSQL and SQLite, generated `lib/database.ts` exposes BCP database primitives through `bcp/database`.
-
-## Authentication and security
-
-The JWT Cookie preset creates starter authentication code. BCP supports revocable session stores, permission/policy authorization, route guards and same-origin/CSRF helpers.
-
-## Background jobs, workflows and events
+Applications can centralize server infrastructure through `bcp/application`:
 
 ```ts
 import {
-    createJobQueue,
-    createJobScheduler,
-} from "bcp/jobs";
-import {
-    createWorkflow,
-} from "bcp/workflow";
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "my-app",
+    });
 ```
 
-Durable Redis-compatible queues/schedules, workflow orchestration and transactional outbox/event delivery are available without forcing a Redis client dependency.
+Existing BCP subsystem APIs remain independently usable.
 
-## Realtime
+## Dependency Injection & Service Container — 0.3.1+
+
+Typed dependencies use `bcp/container`:
 
 ```ts
 import {
-    createRealtime,
-} from "bcp/realtime";
+    createServiceToken,
+    provideFactory,
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
+
+const repositoryToken =
+    createServiceToken<UserRepository>(
+        "user-repository"
+    );
 
-export const realtime =
-    createRealtime();
+export const app =
+    createApp({
+        name: "my-app",
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    apiUrl: "https://api.example.com",
+                }
+            ),
+            provideFactory(
+                repositoryToken,
+                [
+                    configToken,
+                ] as const,
+                (_context, [config]) =>
+                    createRepository(
+                        config.apiUrl
+                    )
+            ),
+        ],
+    });
 ```
 
-BCP does not install a WebSocket server library. Applications adapt their provider to `RealtimeSocket`; SSE is built in.
-
-## Testing
-
-`bcp/testing` provides request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime test harnesses and does not require Jest or Vitest.
-
-## Plugins
-
-`bcp/plugins` provides dependency ordering, module composition, lifecycle hooks, config parsing, shared services and async hooks.
-
-## Cache Platform v2
+Resolve from server/application code:
 
 ```ts
-import {
-    createCacheStore,
-} from "bcp/cache";
-
-export const cache =
-    createCacheStore();
+const repository =
+    await app.container.resolve(
+        repositoryToken
+    );
 ```
 
-Multi-instance applications can use Redis-compatible cache and lock adapters for distributed cache-fill coordination.
+Supported lifetimes:
 
-## Observability Platform v3
+```text
+singleton
+scoped
+transient
+```
 
-```ts
-import {
-    createTracer,
-} from "bcp/observability";
+For request/job/test boundaries:
 
-export const tracer =
-    createTracer({
-        serviceName: "my-app",
+```ts
+const scope =
+    app.createScope({
+        name: "request:123",
     });
 ```
 
-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:
+Testing overrides:
 
 ```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
-
-export const deployment =
-    createDeploymentRuntime({
-        serviceName: "my-app",
+const testScope =
+    app.createScope({
+        name: "test",
+        overrides: [
+            provideValue(
+                mailerToken,
+                fakeMailer
+            ),
+        ],
     });
 ```
 
-Register shared dependencies before components that use them:
+DI is optional. Existing `app.services` and plugin service registries remain supported.
+
+## Lifecycle resources
+
+Long-running infrastructure still uses Deployment Platform resources:
 
 ```ts
-deployment.addResource({
+app.addResource({
     name: "database",
 
-    async start() {
-        await db.connect();
+    start() {
+        return database.connect();
     },
 
     ready() {
-        return db.status === "ready";
-    },
-
-    async stop() {
-        await db.close();
-    },
-});
-
-deployment.addResource({
-    name: "workers",
-
-    start() {
-        worker = jobs.startWorker();
+        return database.ready;
     },
 
-    async stop() {
-        await worker.stop();
+    stop() {
+        return database.close();
     },
 });
-
-await deployment.start();
 ```
 
-Startup follows registration order and shutdown reverses it. This naturally stops workers before database/cache/Redis connections.
+In `0.3.1`, the DI container remains active until application resources and plugins have stopped, then disposes injected services in reverse creation order.
 
-Readiness endpoint:
+## Database presets
 
-```ts
-import {
-    createDeploymentReadinessResponse,
-} from "bcp/deployment";
+- MySQL: `mysql2`
+- PostgreSQL: `pg`
+- SQLite: `better-sqlite3`
+- MongoDB: `mongodb`
+- None: no database dependency
 
-export function GET() {
-    return createDeploymentReadinessResponse(
-        deployment
-    );
-}
-```
+For MySQL, PostgreSQL and SQLite, generated `lib/database.ts` exposes BCP database primitives through `bcp/database`.
 
-Runtime identity can use:
+## Authentication and security
 
-```text
-BCP_DEPLOYMENT_ID
-BCP_INSTANCE_ID
-BCP_RELEASE
-NODE_ENV
-BCP_SHUTDOWN_TIMEOUT_MS
-```
+The JWT Cookie preset creates starter authentication code. BCP supports revocable session stores, permission/policy authorization, route guards and same-origin/CSRF helpers.
 
-Install graceful signal handling with:
+## Jobs, workflows, events and realtime
 
-```ts
-const removeSignals =
-    deployment.installSignalHandlers();
-```
+Use `bcp/jobs`, `bcp/workflow`, `bcp/events` and `bcp/realtime` directly or register selected instances with the Application Platform/DI container.
 
-Default signals are `SIGTERM` and `SIGINT`.
+## Testing
 
-## Stability & API Freeze — 0.2.19
+`bcp/testing` provides framework-native request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime helpers. DI scope overrides complement these helpers for application-level dependency replacement.
 
-`0.2.19` keeps the `0.2.x` public package surface stable before the next platform baseline.
+## Plugins
 
-Framework maintainers can validate the frozen contract with:
+`bcp/plugins` remains available for reusable plugin/module lifecycle composition. Plugin definitions/modules can be passed to `createApp()`.
 
-```bash
-npm run api:check
-npm run release:readiness
-```
+## Observability and deployment
 
-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/observability` provides metrics/tracing. `bcp/deployment` remains available when an application wants to own resource lifecycle directly; `bcp/application` reuses its readiness/diagnostics/shutdown model.
 
 ## Application packaging
 
@@ -271,9 +254,7 @@ npm run build
 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.1` prepared packages include compiled `container.mjs` and `application.mjs` server runtimes. Project `.env` files and application devDependencies are excluded from deployment packages.
 
 ## Project generators
 
@@ -301,5 +282,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.1.tgz
 ```

package/package.json

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

package/template/README.md

@@ -27,162 +27,182 @@ 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.
 
-## 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`.
-
-## Database
+## Application Platform — BCP 0.3.x
 
-MySQL, PostgreSQL and SQLite projects expose the BCP database platform through `bcp/database`.
-
-## Jobs, scheduling and workflows
+For applications with several server subsystems, `bcp/application` provides one optional composition root:
 
 ```ts
 import {
-    createJobQueue,
-    createJobScheduler,
-} from "bcp/jobs";
-import {
-    createWorkflow,
-} from "bcp/workflow";
-```
-
-Durable jobs support leases, heartbeat, stale recovery and DLQ. Workflows support sequential/parallel steps, retries, persisted delays and compensation.
+    createApp,
+} from "bcp/application";
 
-## Transactional events
+export const app =
+    createApp({
+        name: "bcp-app",
+    });
+```
 
-Use `bcp/events` when business data and an integration event must commit in the same SQL transaction. The outbox dispatcher can deliver through durable jobs or an application publisher after commit.
+## Dependency Injection — BCP 0.3.1+
 
-## Realtime
+Use `bcp/container` for typed application dependencies:
 
 ```ts
 import {
-    createRealtime,
-} from "bcp/realtime";
+    createServiceToken,
+    provideFactory,
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
+
+const clientToken =
+    createServiceToken<ApiClient>(
+        "api-client"
+    );
 
-export const realtime =
-    createRealtime();
+export const app =
+    createApp({
+        name: "bcp-app",
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    apiUrl: "https://api.example.com",
+                }
+            ),
+            provideFactory(
+                clientToken,
+                [
+                    configToken,
+                ] as const,
+                (_context, [config]) =>
+                    createApiClient(
+                        config.apiUrl
+                    )
+            ),
+        ],
+    });
 ```
 
-BCP does not install a WebSocket server library. Adapt the selected provider through `RealtimeSocket`; SSE is built in.
-
-## Testing
-
-`bcp/testing` provides request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers without requiring Jest or Vitest.
-
-## Plugins
-
-`bcp/plugins` provides reusable server-side plugins/modules, dependency ordering, lifecycle hooks, config parsing, shared services and awaited hooks.
-
-## Cache Platform v2
+Resolve typed services:
 
 ```ts
-import {
-    createCacheStore,
-} from "bcp/cache";
-
-export const cache =
-    createCacheStore();
+const client =
+    await app.container.resolve(
+        clientToken
+    );
 ```
 
-Use Redis-compatible cache/lock adapters for multi-instance cache-fill coordination when needed.
+Provider lifetimes are `singleton`, `scoped` and `transient`.
 
-## Observability Platform v3
+For request/job/test scopes:
 
 ```ts
-import {
-    createTracer,
-} from "bcp/observability";
-
-export const tracer =
-    createTracer({
-        serviceName: "bcp-app",
+const scope =
+    app.createScope({
+        name: "request:123",
     });
 ```
 
-Tracing supports AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers and provider-neutral exporters.
+Testing overrides can replace selected providers within a child scope without changing the root application container.
 
-## Deployment Platform v2 — BCP 0.2.18+
-
-Use `bcp/deployment` to manage production resource lifecycle:
+The legacy Plugin Platform registry remains supported:
 
 ```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
-
-export const deployment =
-    createDeploymentRuntime({
-        serviceName: "bcp-app",
-    });
+app.provide("database", database);
 ```
 
-Register dependencies first:
+Use typed `ServiceToken<T>` providers for new application dependency injection code.
+
+## Lifecycle resources
+
+Long-running infrastructure uses `app.addResource()`:
 
 ```ts
-deployment.addResource({
+app.addResource({
     name: "database",
 
-    async start() {
-        await db.connect();
+    start() {
+        return database.connect();
     },
 
     ready() {
-        return db.status === "ready";
+        return database.ready;
     },
 
-    async stop() {
-        await db.close();
+    stop() {
+        return database.close();
     },
 });
 ```
 
-Register workers/realtime services afterward so reverse-order shutdown stops them before their shared database/cache/Redis dependencies.
-
-Start runtime:
+Then start the application runtime from server/bootstrap code:
 
 ```ts
-await deployment.start();
+await app.start();
 ```
 
-Readiness endpoint:
+BCP `0.3.1` keeps the DI container alive until application resources/plugins have stopped, then disposes resolved services in reverse creation order.
+
+## 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`.
+
+## Database
+
+MySQL, PostgreSQL and SQLite projects expose database primitives through `bcp/database`.
+
+## Jobs, workflows and events
+
+Use `bcp/jobs`, `bcp/workflow` and `bcp/events` independently or compose instances through the Application Platform.
+
+## Realtime
 
 ```ts
 import {
-    createDeploymentReadinessResponse,
-} from "bcp/deployment";
+    createRealtime,
+} from "bcp/realtime";
 
-export function GET() {
-    return createDeploymentReadinessResponse(
-        deployment
-    );
-}
+export const realtime =
+    createRealtime();
 ```
 
-Install graceful signal handling when the app owns process signals:
+BCP does not install a WebSocket server library. Adapt the selected provider through `RealtimeSocket`; SSE is built in.
 
-```ts
-const removeSignals =
-    deployment.installSignalHandlers();
-```
+## Testing
+
+`bcp/testing` provides framework-native server test helpers. `bcp/container` child-scope overrides can replace application dependencies during tests.
+
+## Plugins
+
+`bcp/plugins` provides reusable server-side plugins/modules, dependency ordering, lifecycle hooks, config parsing, shared services and awaited hooks.
+
+## Cache and observability
+
+`bcp/cache` provides provider-neutral cache/lock primitives. `bcp/observability` provides metrics, health and tracing.
+
+## Deployment lifecycle
 
-Default signals are `SIGTERM` and `SIGINT`.
+`bcp/deployment` remains available for direct lifecycle ownership. `bcp/application` composes the same readiness/diagnostics/shutdown model.
 
-Deployment identity can be supplied through:
+Application startup order in `0.3.1` is:
 
 ```text
-BCP_DEPLOYMENT_ID
-BCP_INSTANCE_ID
-BCP_RELEASE
-NODE_ENV
-BCP_SHUTDOWN_TIMEOUT_MS
+application setup
+container
+plugins
+resources
+application start
 ```
 
-## Stability baseline — BCP 0.2.19
+Shutdown reverses deployment dependencies, then runs application disposal.
 
-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.1` advances `0.3.0` additively with `bcp/container`. Application code should use documented public `bcp/*` entrypoints and avoid private framework `packages/*` paths.
 
 ## Production build
 
@@ -197,9 +217,9 @@ npm start
 npm run package
 ```
 
-BCP excludes project `.env` files and application `devDependencies` from the deployment package. Supply secrets through the deployment environment.
+BCP excludes project `.env` files and application `devDependencies` from deployment packages. 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.
+Prepared `0.3.1` packages include compiled `container.mjs` and `application.mjs` runtimes.
 
 ## Direct CLI usage