@chidchanun/bcp 0.2.18 → 0.2.19

package/docs/api-freeze-snapshot.json

@@ -0,0 +1,232 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.2.19",
+  "baselineVersion": "0.2.18",
+  "state": "frozen",
+  "intentionalBreakingChanges": false,
+  "publicEntrypoints": [
+    "bcp",
+    "bcp/island",
+    "bcp/cache",
+    "bcp/config",
+    "bcp/validation",
+    "bcp/error",
+    "bcp/database",
+    "bcp/auth",
+    "bcp/jobs",
+    "bcp/workflow",
+    "bcp/events",
+    "bcp/realtime",
+    "bcp/testing",
+    "bcp/plugins",
+    "bcp/observability",
+    "bcp/deployment",
+    "bcp/server",
+    "bcp/server-only",
+    "bcp/middleware"
+  ],
+  "cliCommands": [
+    "dev",
+    "build",
+    "package",
+    "start",
+    "routes",
+    "update",
+    "db",
+    "generate",
+    "config",
+    "doctor",
+    "inspect",
+    "help",
+    "version"
+  ],
+  "packageExports": {
+    ".": {
+      "default": "./packages/client/src/index.tsx",
+      "types": "./packages/client/src/index.tsx"
+    },
+    "./auth": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/auth.mjs",
+      "types": "./packages/client/src/auth.ts"
+    },
+    "./cache": {
+      "default": "./packages/client/src/cache.mjs",
+      "types": "./packages/client/src/cache.ts"
+    },
+    "./config": {
+      "default": "./packages/client/src/config.mjs",
+      "types": "./packages/client/src/config.ts"
+    },
+    "./database": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/database.mjs",
+      "types": "./packages/client/src/database.ts"
+    },
+    "./deployment": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/deployment.mjs",
+      "types": "./packages/client/src/deployment.ts"
+    },
+    "./error": {
+      "default": "./packages/client/src/http-error.ts",
+      "types": "./packages/client/src/http-error.ts"
+    },
+    "./events": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/events.mjs",
+      "types": "./packages/client/src/events.ts"
+    },
+    "./island": {
+      "default": "./packages/client/src/islands.tsx",
+      "types": "./packages/client/src/islands.tsx"
+    },
+    "./jobs": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/jobs.mjs",
+      "types": "./packages/client/src/jobs.ts"
+    },
+    "./middleware": {
+      "default": "./packages/server/src/middleware.mjs",
+      "types": "./packages/server/src/middleware.ts"
+    },
+    "./observability": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/observability.mjs",
+      "types": "./packages/client/src/observability.ts"
+    },
+    "./package.json": "./package.json",
+    "./plugins": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/plugins.mjs",
+      "types": "./packages/client/src/plugins.ts"
+    },
+    "./realtime": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/realtime.mjs",
+      "types": "./packages/client/src/realtime.ts"
+    },
+    "./server": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server.mjs",
+      "types": "./packages/client/src/server.ts"
+    },
+    "./server-only": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server-only.mjs",
+      "types": "./packages/client/src/server-only.d.ts"
+    },
+    "./testing": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/testing.mjs",
+      "types": "./packages/client/src/testing.ts"
+    },
+    "./validation": {
+      "default": "./packages/client/src/validation.ts",
+      "types": "./packages/client/src/validation.ts"
+    },
+    "./workflow": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/workflow.mjs",
+      "types": "./packages/client/src/workflow.ts"
+    }
+  },
+  "apiOwnership": [
+    {
+      "package": "bcp",
+      "source": "packages/client/src/index.tsx",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/island",
+      "source": "packages/client/src/islands.tsx",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/cache",
+      "source": "packages/client/src/cache.ts",
+      "environment": "server-preferred"
+    },
+    {
+      "package": "bcp/config",
+      "source": "packages/client/src/config.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/validation",
+      "source": "packages/client/src/validation.ts",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/error",
+      "source": "packages/client/src/http-error.ts",
+      "environment": "universal"
+    },
+    {
+      "package": "bcp/database",
+      "source": "packages/client/src/database.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/auth",
+      "source": "packages/client/src/auth.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/jobs",
+      "source": "packages/client/src/jobs.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/workflow",
+      "source": "packages/client/src/workflow.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/events",
+      "source": "packages/client/src/events.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/realtime",
+      "source": "packages/client/src/realtime.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/testing",
+      "source": "packages/client/src/testing.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/plugins",
+      "source": "packages/client/src/plugins.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/observability",
+      "source": "packages/client/src/observability.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/deployment",
+      "source": "packages/client/src/deployment.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/server",
+      "source": "packages/client/src/server.ts",
+      "environment": "server"
+    },
+    {
+      "package": "bcp/server-only",
+      "source": "packages/client/src/server-only.mjs",
+      "environment": "server-marker"
+    },
+    {
+      "package": "bcp/middleware",
+      "source": "packages/server/src/middleware.ts",
+      "environment": "server"
+    }
+  ]
+}

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.18",
+  "versionTarget": "0.2.19",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -102,9 +102,10 @@
     {
       "id": "platform-compatibility",
       "title": "Platform & Compatibility",
-      "description": "Supported platform contracts, documentation integration and migration guidance.",
+      "description": "Supported platform contracts, API freeze, documentation integration and migration guidance.",
       "pages": [
         { "route": "/docs/platform-contract", "source": "platform-contract.md", "title": "Framework Platform Contract" },
+        { "route": "/docs/stability-api-freeze", "source": "stability-api-freeze.md", "title": "Stability & API Freeze" },
         { "route": "/docs/documentation-platform", "source": "documentation-platform.md", "title": "Documentation Platform" },
         { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.x" }
       ]
@@ -119,7 +120,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.18", "source": "releases/0.2.18.md", "version": "0.2.18", "state": "unreleased" },
+    { "route": "/releases/0.2.19", "source": "releases/0.2.19.md", "version": "0.2.19", "state": "unreleased" },
+    { "route": "/releases/0.2.18", "source": "releases/0.2.18.md", "version": "0.2.18" },
     { "route": "/releases/0.2.17", "source": "releases/0.2.17.md", "version": "0.2.17" },
     { "route": "/releases/0.2.16", "source": "releases/0.2.16.md", "version": "0.2.16" },
     { "route": "/releases/0.2.15", "source": "releases/0.2.15.md", "version": "0.2.15" },

package/docs/migration-0.2.md

@@ -1,63 +1,62 @@
-# Migrating to BCP Framework 0.2.0
+# Migrating within BCP Framework 0.2.x
 
-BCP Framework `0.2.0` establishes the Framework Platform baseline while preserving the public application model from `0.1.29`.
+BCP Framework `0.2.19` is the final `0.2.x` stability/API-freeze baseline before `0.3.0`.
 
-> **Release state:** unreleased development target until RC validation and npm publication complete.
+> **Current development target:** `0.2.19 — Stability & API Freeze`
+>
+> Release state remains unreleased until the complete RC sequence, tagging and npm publication finish.
 
 ## Compatibility goal
 
-There are no intentional public-entrypoint removals from the `0.1.29` baseline in this milestone.
+`0.2.19` declares no intentional breaking changes from `0.2.18`.
 
-Applications already running on `0.1.29` should normally be able to move to `0.2.0` without rewriting routing, loaders, guards, actions, middleware, storage or authentication code.
+The supported `0.2.x` public entrypoint/package-resolution contract is frozen in:
 
-BCP remains pre-1.0, so every application should still validate the upgrade before production deployment.
+```text
+docs/api-freeze-snapshot.json
+```
 
-## 1. Check the current project
+Applications should continue importing documented `bcp/*` entrypoints and avoid framework-private `packages/*` paths.
 
-From the application root:
+## 1. Inspect the current application
 
 ```powershell
 npm exec -- bcp-framework doctor
 npm exec -- bcp-framework inspect --json
+npm exec -- bcp-framework update --check
 ```
 
-Resolve blocking `FAIL` results before upgrading, especially duplicate framework dependency declarations or invalid production-hardening settings.
+Resolve blocking diagnostics before upgrading.
 
-## 2. Check the available framework update
-
-```powershell
-npm exec -- bcp-framework update --check
-```
+## 2. Upgrade explicitly
 
-After `0.2.0` is published, update with:
+After `0.2.19` is published:
 
 ```powershell
-npm exec -- bcp-framework update 0.2.0
+npm exec -- bcp-framework update 0.2.19
 ```
 
-Generated projects can also use:
+Generated applications can also use:
 
 ```powershell
-npm run update -- 0.2.0
+npm run update -- 0.2.19
 ```
 
-## 3. Keep one framework dependency
-
-The recommended project dependency remains:
+The recommended dependency remains one BCP installation:
 
 ```json
 {
   "dependencies": {
-    "bcp": "npm:@chidchanun/bcp@0.2.0"
+    "bcp": "npm:@chidchanun/bcp@0.2.19"
   }
 }
 ```
 
-Do not keep both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application. Two installed framework copies can produce separate React/framework contexts.
+Do not keep both the `bcp` alias and a second direct `@chidchanun/bcp` dependency in the same application.
 
-## 4. Preserve server-only boundaries
+## 3. Keep public import boundaries
 
-Continue importing public APIs through supported entrypoints such as:
+Examples:
 
 ```ts
 import {
@@ -65,37 +64,61 @@ import {
 } from "bcp";
 
 import {
-    auth,
+    createAuth,
 } from "bcp/auth";
 
 import {
     db,
 } from "bcp/database";
 
+import {
+    createJobQueue,
+} from "bcp/jobs";
+
+import {
+    createDeploymentRuntime,
+} from "bcp/deployment";
+
 import {
     cookies,
 } from "bcp/server";
 ```
 
-Do not migrate application imports to framework-internal `packages/...` paths.
+The frozen entrypoint list is documented in [Framework Platform Contract](platform-contract.md) and [Stability & API Freeze](stability-api-freeze.md).
 
-The current public entrypoint baseline is listed in `platform-manifest.json` and [Framework Platform Contract](platform-contract.md).
+## 4. Rebuild production artifacts
 
-## 5. Validate generated-project metadata
+Do not reuse an old `.bcp-framework/build` or `.bcp-framework/package` directory after changing framework versions.
 
-Projects created by `create-bcp-app` `0.1.29` or newer may contain:
+Run:
 
-```text
-bcp.project.json
+```powershell
+npm run build
+npm run package
+```
+
+Then test the production runtime:
+
+```powershell
+npm start
 ```
 
-This file is optional runtime metadata. Older applications do not need to create it manually to run on `0.2.0`.
+## 5. Deployment/runtime review
 
-If you choose to add it to an older application, keep it non-secret. Credentials, passwords, access keys, session secrets and tokens do not belong in this file.
+For applications adopting Deployment Platform v2, consider registering long-lived resources such as:
+
+```text
+database
+cache/redis connections
+background workers
+realtime services
+outbox dispatchers
+workflow workers
+```
 
-## 6. Validate production settings
+in dependency order so reverse-order shutdown drains dependents before shared infrastructure closes.
 
-For standalone production, review:
+Review production environment settings such as:
 
 ```dotenv
 BCP_REQUEST_TIMEOUT_MS=120000
@@ -105,35 +128,17 @@ BCP_SHUTDOWN_TIMEOUT_MS=10000
 BCP_TRUST_PROXY=false
 ```
 
-Only enable:
+Deployment identity may additionally use:
 
 ```dotenv
-BCP_TRUST_PROXY=true
+BCP_DEPLOYMENT_ID=
+BCP_INSTANCE_ID=
+BCP_RELEASE=
 ```
 
-when the BCP process is reachable only through a trusted reverse proxy/load balancer.
+## 6. Application validation
 
-## 7. Rebuild the standalone artifact
-
-Do not reuse `.bcp-framework/build` from the previous framework version.
-
-Run:
-
-```powershell
-npm run build
-```
-
-Then test:
-
-```powershell
-npm start
-```
-
-The supported `0.2.0` production target remains the standalone Node.js artifact under `.bcp-framework/build/`.
-
-## 8. Application validation checklist
-
-Recommended minimum after upgrading:
+Recommended minimum:
 
 ```powershell
 npm run typecheck
@@ -142,32 +147,26 @@ npm exec -- bcp-framework routes
 npm exec -- bcp-framework doctor
 ```
 
-For applications using authentication, storage or database features, also exercise representative login/session, upload/download and database paths before production deployment.
+For applications using authentication, databases, storage, jobs, workflows, events, realtime or cache, exercise representative production paths before rollout.
 
-## Local storage projects
+## 7. What the 0.2.19 freeze means for applications
 
-Projects using the Local Server storage preset should keep the scaffold:
-
-```text
-storage/
-├─ .gitkeep
-└─ README.md
-```
+The freeze is a **framework release contract**, not a new runtime requirement for applications.
 
-Runtime storage objects remain ignored by Git.
+Applications do not need to run the framework repository's `api:check` or `release:readiness` scripts. Those are maintainer release gates.
 
-## Amazon S3 / Cloudflare R2 projects
+The practical application rule is:
 
-No provider migration is required for the `0.2.0` platform baseline. Existing `createS3Storage()` configurations continue using server-only credentials/environment settings.
-
-## What is not part of this migration
+```text
+use documented bcp/* entrypoints
+avoid private packages/* imports
+validate upgrades before deployment
+```
 
-`0.2.0` does not introduce native executable compilation, desktop packaging, Android APK output or iOS application output.
+## 8. Moving from 0.2.19 to 0.3.0
 
-The supported build model remains:
+`0.2.19` becomes the compatibility reference point for the next platform baseline.
 
-```text
-BCP application -> bcp build -> standalone Node.js web application
-```
+If `0.3.0` intentionally changes the frozen public surface, its release should provide explicit compatibility metadata and migration guidance rather than silently changing a `0.2.x` contract.
 
-Future build targets can be added after the platform baseline without redefining the existing standalone contract.
+Native executable/mobile/desktop compilation is still outside the current standalone Node.js web-application target.