@chidchanun/bcp 0.1.29 → 0.2.0

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.1.29",
+  "versionTarget": "0.2.0",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -75,10 +75,19 @@
         { "route": "/docs/generators", "source": "generators.md", "title": "Project Generators" },
         { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" }
       ]
+    },
+    {
+      "id": "platform-compatibility",
+      "title": "Platform & Compatibility",
+      "pages": [
+        { "route": "/docs/platform-contract", "source": "platform-contract.md", "title": "Framework Platform Contract" },
+        { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.0" }
+      ]
     }
   ],
   "releases": [
-    { "route": "/releases/0.1.29", "source": "releases/0.1.29.md", "version": "0.1.29", "state": "unreleased" },
+    { "route": "/releases/0.2.0", "source": "releases/0.2.0.md", "version": "0.2.0", "state": "unreleased" },
+    { "route": "/releases/0.1.29", "source": "releases/0.1.29.md", "version": "0.1.29" },
     { "route": "/releases/0.1.28", "source": "releases/0.1.28.md", "version": "0.1.28" },
     { "route": "/releases/0.1.27", "source": "releases/0.1.27.md", "version": "0.1.27" },
     { "route": "/releases/0.1.26", "source": "releases/0.1.26.md", "version": "0.1.26" },

package/docs/migration-0.2.md

@@ -0,0 +1,173 @@
+# Migrating to BCP Framework 0.2.0
+
+BCP Framework `0.2.0` establishes the Framework Platform baseline while preserving the public application model from `0.1.29`.
+
+> **Release state:** unreleased development target until RC validation and npm publication complete.
+
+## Compatibility goal
+
+There are no intentional public-entrypoint removals from the `0.1.29` baseline in this milestone.
+
+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.
+
+BCP remains pre-1.0, so every application should still validate the upgrade before production deployment.
+
+## 1. Check the current project
+
+From the application root:
+
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect --json
+```
+
+Resolve blocking `FAIL` results before upgrading, especially duplicate framework dependency declarations or invalid production-hardening settings.
+
+## 2. Check the available framework update
+
+```powershell
+npm exec -- bcp-framework update --check
+```
+
+After `0.2.0` is published, update with:
+
+```powershell
+npm exec -- bcp-framework update 0.2.0
+```
+
+Generated projects can also use:
+
+```powershell
+npm run update -- 0.2.0
+```
+
+## 3. Keep one framework dependency
+
+The recommended project dependency remains:
+
+```json
+{
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@0.2.0"
+  }
+}
+```
+
+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.
+
+## 4. Preserve server-only boundaries
+
+Continue importing public APIs through supported entrypoints such as:
+
+```ts
+import {
+    Form,
+} from "bcp";
+
+import {
+    auth,
+} from "bcp/auth";
+
+import {
+    db,
+} from "bcp/database";
+
+import {
+    cookies,
+} from "bcp/server";
+```
+
+Do not migrate application imports to framework-internal `packages/...` paths.
+
+The current public entrypoint baseline is listed in `platform-manifest.json` and [Framework Platform Contract](platform-contract.md).
+
+## 5. Validate generated-project metadata
+
+Projects created by `create-bcp-app` `0.1.29` or newer may contain:
+
+```text
+bcp.project.json
+```
+
+This file is optional runtime metadata. Older applications do not need to create it manually to run on `0.2.0`.
+
+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.
+
+## 6. Validate production settings
+
+For standalone production, review:
+
+```dotenv
+BCP_REQUEST_TIMEOUT_MS=120000
+BCP_HEADERS_TIMEOUT_MS=66000
+BCP_KEEP_ALIVE_TIMEOUT_MS=65000
+BCP_SHUTDOWN_TIMEOUT_MS=10000
+BCP_TRUST_PROXY=false
+```
+
+Only enable:
+
+```dotenv
+BCP_TRUST_PROXY=true
+```
+
+when the BCP process is reachable only through a trusted reverse proxy/load balancer.
+
+## 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:
+
+```powershell
+npm run typecheck
+npm run build
+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.
+
+## Local storage projects
+
+Projects using the Local Server storage preset should keep the scaffold:
+
+```text
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+Runtime storage objects remain ignored by Git.
+
+## Amazon S3 / Cloudflare R2 projects
+
+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
+
+`0.2.0` does not introduce native executable compilation, desktop packaging, Android APK output or iOS application output.
+
+The supported build model remains:
+
+```text
+BCP application -> bcp build -> standalone Node.js web application
+```
+
+Future build targets can be added after the platform baseline without redefining the existing standalone contract.

package/docs/platform-contract.md

@@ -0,0 +1,159 @@
+# Framework Platform Contract
+
+BCP Framework `0.2.0` establishes the first explicit framework-platform baseline. The goal is to make public entrypoints, supported runtime targets, CLI capabilities and documentation metadata visible and testable instead of relying on implicit package structure.
+
+> **Release state:** unreleased development target until local RC validation, tagging and npm publication complete.
+
+## What the platform contract covers
+
+The platform contract is represented by `docs/platform-manifest.json` and release/package smoke tests.
+
+It records:
+
+- the framework version and release state,
+- the minimum supported Node.js runtime,
+- the supported production build target,
+- public package entrypoints,
+- documented CLI command families,
+- framework capability groups,
+- built-in/scaffolded storage-provider families,
+- compatibility expectations for the previous baseline,
+- documentation files used by `bcp-docs-web`.
+
+The manifest is metadata. Framework source, package exports and tests remain authoritative for actual runtime behavior.
+
+## Public entrypoints
+
+The `0.2.0` platform baseline recognizes these public application imports:
+
+```text
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/server
+bcp/server-only
+bcp/middleware
+```
+
+Application code should prefer these entrypoints instead of importing internal files under `packages/`.
+
+The release package contract smoke test verifies that the prepared npm artifact still exposes these entrypoints. Accidentally removing one from the publish manifest should fail package validation before release.
+
+## CLI baseline
+
+The framework-platform CLI baseline includes:
+
+```text
+bcp dev
+bcp build
+bcp start
+bcp routes
+bcp update
+bcp db ...
+bcp generate ...
+bcp doctor
+bcp inspect
+bcp help
+bcp version
+```
+
+The Windows-safe `bcp-framework` executable remains an alias for the same CLI.
+
+## Runtime baseline
+
+BCP `0.2.0` continues to target a standalone Node.js web application:
+
+```text
+BCP source application
+        ↓
+     bcp build
+        ↓
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   └─ server.mjs
+```
+
+Minimum runtime:
+
+```text
+Node.js >= 24.11.0
+React 19
+```
+
+The platform baseline does not yet promise native `.exe`, mobile or desktop application compilation. Those remain future build-target work rather than part of `0.2.0`.
+
+## Compatibility policy for 0.2.0
+
+`0.2.0` is intended to preserve applications that already work on `0.1.29`. This milestone does not intentionally remove public entrypoints or change the current standalone runtime model.
+
+Because BCP remains pre-1.0, applications should still validate upgrades through:
+
+```bash
+bcp update --check
+bcp doctor
+npm run typecheck
+npm run build
+```
+
+See [Migrating to 0.2.0](migration-0.2.md).
+
+## Package consistency validation
+
+The `0.2.0` release process adds a platform-contract package smoke check. It verifies the staged npm artifact rather than only source files.
+
+The check covers:
+
+1. framework version consistency,
+2. required public package exports,
+3. both BCP CLI executable aliases,
+4. minimum Node.js engine declaration,
+5. inclusion of platform/docs metadata in the packed framework,
+6. docs-web target/version consistency,
+7. create-bcp-app version parity with the framework release.
+
+This is additive to existing unit, integration, E2E, storage, production-hardening and Developer Experience package smoke checks.
+
+## Docs-web contract
+
+`bcp-docs-web` should use two machine-readable files for different purposes:
+
+```text
+docs/docs-web-manifest.json
+  -> website sections, routes, source Markdown and release navigation
+
+docs/platform-manifest.json
+  -> framework version, public entrypoints, runtime target and capability metadata
+```
+
+Do not duplicate the platform entrypoint list in application code when it can be sourced from `platform-manifest.json`.
+
+## Stability labels
+
+Documentation should distinguish:
+
+- **platform baseline** — public surface covered by the `0.2.0` contract,
+- **supported** — behavior covered by current tests/docs,
+- **experimental/roadmap** — not guaranteed by the current platform manifest,
+- **internal** — not a public application import contract.
+
+## Release validation
+
+Before `0.2.0` is tagged or published:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:package
+npm run test:e2e
+npm run rc:check
+```
+
+The release is not considered published until both `@chidchanun/bcp@0.2.0` and `create-bcp-app@0.2.0` are visible from npm.

package/docs/platform-manifest.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.2.0",
+  "releaseState": "unreleased",
+  "baseline": "framework-platform",
+  "runtime": {
+    "node": ">=24.11.0",
+    "react": "19",
+    "buildTarget": "standalone-node"
+  },
+  "publicEntrypoints": [
+    "bcp",
+    "bcp/island",
+    "bcp/cache",
+    "bcp/config",
+    "bcp/validation",
+    "bcp/error",
+    "bcp/database",
+    "bcp/auth",
+    "bcp/server",
+    "bcp/server-only",
+    "bcp/middleware"
+  ],
+  "cliCommands": [
+    "dev",
+    "build",
+    "start",
+    "routes",
+    "update",
+    "db",
+    "generate",
+    "doctor",
+    "inspect",
+    "help",
+    "version"
+  ],
+  "capabilities": {
+    "routing": true,
+    "ssr": true,
+    "spaNavigation": true,
+    "loaders": true,
+    "routeGuards": true,
+    "formActions": true,
+    "middlewareV2": true,
+    "jwtCookieSessions": true,
+    "databaseMigrations": true,
+    "validation": true,
+    "structuredErrors": true,
+    "logging": true,
+    "responseCaching": true,
+    "streamingUploads": true,
+    "storageEcosystem": true,
+    "productionHardening": true,
+    "projectGenerators": true,
+    "projectDiagnostics": true
+  },
+  "storageProviders": [
+    "local",
+    "amazon-s3",
+    "cloudflare-r2",
+    "s3-compatible"
+  ],
+  "compatibility": {
+    "previousBaseline": "0.1.29",
+    "intentionalBreakingChangesFromPreviousBaseline": false,
+    "migrationGuide": "migration-0.2.md"
+  },
+  "documentation": {
+    "navigationManifest": "docs-web-manifest.json",
+    "platformContract": "platform-contract.md",
+    "migrationGuide": "migration-0.2.md",
+    "releaseNotes": "releases/0.2.0.md"
+  }
+}

package/docs/releases/0.2.0.md

@@ -0,0 +1,146 @@
+# BCP Framework 0.2.0
+
+> **Milestone:** Framework Platform
+>
+> **Release state:** unreleased development target. Do not mark this version as published until local validation, RC checks, tagging and npm publication complete.
+
+BCP Framework `0.2.0` establishes an explicit platform baseline for the public package surface, runtime target, CLI families and documentation metadata built across the `0.1.x` releases.
+
+## Highlights
+
+### Framework platform manifest
+
+New machine-readable source:
+
+```text
+docs/platform-manifest.json
+```
+
+It records:
+
+- framework version/release state,
+- minimum Node.js and React baseline,
+- standalone production build target,
+- public application entrypoints,
+- CLI command families,
+- capability groups,
+- storage-provider families,
+- previous-baseline compatibility intent,
+- documentation contract files.
+
+The manifest is intended for tooling and `bcp-docs-web`; framework source and tests remain authoritative for runtime behavior.
+
+### Public entrypoint contract
+
+The platform baseline explicitly recognizes:
+
+```text
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/server
+bcp/server-only
+bcp/middleware
+```
+
+A new package-stage smoke check validates that prepared npm artifacts preserve the required exports before release.
+
+### Package/release consistency
+
+The `0.2.0` package validation adds checks for:
+
+- framework/create-app version parity,
+- required public exports,
+- `bcp` and `bcp-framework` executable aliases,
+- minimum Node.js engine declaration,
+- inclusion of the platform manifest/contract/migration guide/release notes,
+- docs-web version target consistency.
+
+This validation runs in addition to existing runtime, storage, hardening and Developer Experience smoke tests.
+
+### Migration guide
+
+New guide:
+
+```text
+docs/migration-0.2.md
+```
+
+The `0.2.0` milestone does not intentionally remove public entrypoints from the `0.1.29` baseline. Existing applications should still run normal upgrade validation because BCP remains pre-1.0.
+
+### Docs-web platform source
+
+`bcp-docs-web` now has two explicit machine-readable framework sources:
+
+```text
+docs/docs-web-manifest.json
+  -> navigation/routes/Markdown sources
+
+docs/platform-manifest.json
+  -> version/runtime/public-entrypoint/capability contract
+```
+
+The docs-web navigation includes the platform contract and `0.2.0` migration guide.
+
+## Runtime/build target
+
+The supported production output remains:
+
+```text
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   └─ server.mjs
+```
+
+`0.2.0` does not yet add native `.exe`, desktop or mobile build targets.
+
+## Compatibility
+
+Compatibility goal from `0.1.29`:
+
+```text
+intentional public-entrypoint removals: none
+standalone runtime model change: none
+create-bcp-app project model change: none required
+```
+
+Projects should still run:
+
+```bash
+bcp doctor
+npm run typecheck
+npm run build
+```
+
+before production deployment after the upgrade.
+
+## Documentation
+
+New/updated platform documents:
+
+- `docs/platform-manifest.json`
+- `docs/platform-contract.md`
+- `docs/migration-0.2.md`
+- `docs/docs-web-manifest.json`
+- `docs/README.md`
+- root `README.md`
+
+## Validation required before release
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:package
+npm run test:e2e
+npm run rc:check
+```
+
+Do not tag or publish `v0.2.0` until these pass against the final release commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.29",
+  "version": "0.2.0",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",