@chidchanun/bcp 0.1.29 → 0.2.0

package/README.md

@@ -1,10 +1,38 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework focused on file-based routing, SSR, server data loading, guarded application flows, API routes, authentication, database access, validation, logging, uploads, storage and standalone production deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, database access, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.1.29`
+> **Development target:** `0.2.0 — Framework Platform`
 >
-> BCP is pre-1.0. The `0.1.29` source adds the Developer Experience milestone and remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.0` establishes the first explicit platform baseline for BCP. It remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+
+## Platform baseline — 0.2.0
+
+BCP `0.2.0` consolidates the capabilities built across the `0.1.x` series into a documented and testable platform contract.
+
+New platform sources:
+
+```text
+docs/platform-manifest.json
+  -> version, runtime target, public entrypoints and capability metadata
+
+docs/docs-web-manifest.json
+  -> docs-web sections, routes, Markdown sources and releases
+
+docs/platform-contract.md
+  -> public platform/compatibility contract
+
+docs/migration-0.2.md
+  -> application upgrade guide
+```
+
+The package release pipeline now verifies the platform contract against the prepared npm artifact so accidental public-export/version drift fails package validation.
+
+Read more:
+
+- [Framework Platform Contract](docs/platform-contract.md)
+- [Migrating to 0.2.0](docs/migration-0.2.md)
+- [Platform Manifest](docs/platform-manifest.json)
 
 ## Current capabilities
 
@@ -12,29 +40,29 @@ BCP Framework is a React full-stack framework focused on file-based routing, SSR
 | --- | --- |
 | Application | React SSR, hydration, layouts, metadata and SPA navigation |
 | Routing | Static, dynamic, catch-all, optional catch-all and route groups |
-| Server data | `loader.ts`, request-scoped server APIs |
+| Server data | Route `loader.ts`, request-scoped server APIs |
 | Mutations | Route-owned `actions.ts` and `<Form>` |
 | Authorization | `guard.ts`, `requireAuth()`, `requireRole()` |
 | Authentication | JWT cookie sessions and auth helpers |
 | Middleware | Middleware System v2 with onion execution |
 | Validation | Typed validation helpers and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
-| Database | MySQL pool/query helpers, transactions and migrations |
+| Database | MySQL helpers, transactions and migrations |
 | Logging | Structured logger, request logger and request IDs |
 | Uploads | Buffered multipart helpers and production multipart streaming |
-| Storage | Local + S3-compatible adapters, streaming, listing, copy/move, metadata, bulk delete and signed S3 URLs |
+| Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
 | Caching | Response cache and revalidation primitives |
-| Developer tools | Project generators, `doctor` / `inspect` v2, updater, route inspection and project metadata |
-| Production | Standalone build, hardening gateway, graceful shutdown, trusted-proxy controls and HTTP timeouts |
-| Documentation | Markdown source map plus `docs/docs-web-manifest.json` for `bcp-docs-web` |
+| Developer tools | Generators, Doctor/Inspect v2, updater, route inspection and project metadata |
+| Production | Standalone Node.js build, hardening gateway, graceful shutdown, trusted proxy controls and HTTP timeouts |
+| Documentation | Markdown source + machine-readable docs-web/platform manifests |
 
 ## Requirements
 
-- Node.js `24.11` or newer
+- Node.js `24.11.0` or newer
 - React `19`
 - npm
 
-Database features currently target MySQL.
+Database framework primitives currently target MySQL. `create-bcp-app` can also scaffold PostgreSQL, SQLite and MongoDB application helpers.
 
 ## Quick start
 
@@ -44,32 +72,24 @@ cd my-app
 npm run dev
 ```
 
-Generated projects normally use the application dependency key `bcp`:
+Generated projects normally keep one framework dependency key:
 
 ```json
 {
   "dependencies": {
     "bcp": "npm:@chidchanun/bcp@latest"
-  },
-  "scripts": {
-    "dev": "bcp dev",
-    "build": "bcp build",
-    "start": "bcp start",
-    "routes": "bcp routes",
-    "update": "bcp update",
-    "typecheck": "tsc --noEmit"
   }
 }
 ```
 
-Keep only one framework dependency named `bcp`. Installing both `bcp` and `@chidchanun/bcp` directly can load duplicate framework/React contexts.
+Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application; duplicate framework copies can create separate React/framework contexts.
 
 ## Application model
 
 ```text
 Browser
   ↓
-BCP security / middleware / cache
+Security / middleware / cache
   ↓
 Route guard
   ↓
@@ -80,7 +100,7 @@ React SSR
 Hydration / SPA navigation
 ```
 
-A route can keep page, loader, guard and actions together:
+Typical route structure:
 
 ```text
 app/
@@ -98,73 +118,101 @@ app/
       └─ route.ts
 ```
 
-## Routing
+## Public entrypoints
 
-Page routes are discovered from `app/**/page.tsx` and API routes from `app/**/route.ts`.
+The `0.2.0` platform contract recognizes these application entrypoints:
 
 ```text
-app/page.tsx                     /
-app/about/page.tsx               /about
-app/users/[id]/page.tsx          /users/:id
-app/docs/[...slug]/page.tsx      /docs/*
-app/catalog/[[...slug]]/page.tsx /catalog and /catalog/*
-app/(admin)/settings/page.tsx    /settings
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/server
+bcp/server-only
+bcp/middleware
+```
 
-app/api/users/route.ts           /api/users
-app/api/users/[id]/route.ts      /api/users/:id
+Application code should use public entrypoints rather than importing internal framework files under `packages/`.
+
+The authoritative machine-readable list is in [docs/platform-manifest.json](docs/platform-manifest.json).
+
+## CLI
+
+Core commands:
+
+```bash
+bcp dev
+bcp build
+bcp start
+bcp routes
+bcp update
+bcp doctor
+bcp inspect
+bcp version
 ```
 
-Read more: [Routing](docs/routing.md)
+Database migrations:
 
-## Project generators — 0.1.29
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
 
-BCP `0.1.29` adds generators for common framework files:
+Project generators:
 
 ```bash
 bcp generate page dashboard/users
-bcp generate page users/[id]
 bcp generate api users
 bcp generate middleware
 bcp generate migration create_users
 ```
 
-Generated targets:
-
-```text
-page       -> app/<route>/page.tsx
-api        -> app/api/<route>/route.ts
-middleware -> middleware.ts
-migration  -> migrations/<timestamp>_<name>.ts
-```
+Page/API/middleware generators require `--force` before replacing an existing scaffold target.
 
-Page/API/middleware generators do not overwrite existing files unless `--force` is explicitly supplied:
+On Windows, Microsoft SQL Server may provide another `bcp.exe`. For direct PowerShell usage prefer the collision-free project-local alias:
 
-```bash
-bcp generate page dashboard/users --force
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework generate page dashboard/users
 ```
 
-Migration generation reuses the existing database migration implementation so migration naming and format remain centralized.
+Inside npm scripts, `bcp` remains safe because npm prepends the project `node_modules/.bin` directory to `PATH`.
 
-Read more: [Project Generators](docs/generators.md)
+## Routing, loaders, guards and actions
 
-## Server data, guards and actions
+BCP discovers pages from `app/**/page.tsx` and API handlers from `app/**/route.ts`.
 
-Server loaders live next to their route in `loader.ts`. Route authorization can be defined in `guard.ts`, while route-owned mutations live in `actions.ts`.
+```text
+app/page.tsx                     /
+app/users/[id]/page.tsx          /users/:id
+app/docs/[...slug]/page.tsx      /docs/*
+app/catalog/[[...slug]]/page.tsx /catalog and /catalog/*
+app/(admin)/settings/page.tsx    /settings
+app/api/users/route.ts           /api/users
+```
 
-```ts
-import {
-    requireRole,
-} from "bcp/auth";
+Route-owned server features stay colocated:
 
-export const guard =
-    requireRole("admin");
+```text
+page.tsx
+loader.ts
+guard.ts
+actions.ts
 ```
 
-Read more:
+Guides:
 
+- [Routing](docs/routing.md)
 - [Server Data Loaders](docs/server-data-loaders.md)
 - [Route Guards](docs/route-guards.md)
-- [Auth Route Guards](docs/auth-route-guards.md)
 - [Form Actions](docs/form-actions.md)
 
 ## Authentication and server APIs
@@ -185,9 +233,7 @@ import {
 } from "bcp/server";
 ```
 
-BCP also exposes lower-level JWT cookie session primitives through `bcp/server`.
-
-Read more:
+Guides:
 
 - [Authentication](docs/authentication.md)
 - [JWT Sessions](docs/session-auth.md)
@@ -201,180 +247,76 @@ import {
 } from "bcp/database";
 ```
 
-The database layer provides lazy MySQL pool creation, prepared execution, query helpers, transactions and migrations.
+BCP's database layer includes lazy MySQL pool creation, query/execute helpers, transactions and migrations.
 
-```bash
-bcp db create create_users
-bcp db migrate
-bcp db status
-bcp db rollback
-```
-
-Read more:
+Guides:
 
 - [Database](docs/database.md)
 - [Database Migrations](docs/database-migrations.md)
 
-## Uploads and streaming
-
-BCP supports the original buffered multipart helpers as well as production multipart-to-storage streaming:
-
-```ts
-import {
-    storeMultipartFile,
-} from "bcp/server";
-
-const stored =
-    await storeMultipartFile(
-        request,
-        {
-            storage,
-            fieldName: "file",
-            key: "documents/report.pdf",
-            maxBytes: 100 * 1024 * 1024,
-            constraints: {
-                maxBytes: 80 * 1024 * 1024,
-                allowedTypes: [
-                    "application/pdf",
-                ],
-            },
-        }
-    );
-```
-
-`storeMultipartFile()` consumes `Request.body` incrementally and streams the selected file directly into storage. Request/body infrastructure limits still apply.
+## Storage and uploads
 
-Read more: [File Upload](docs/file-upload.md)
+`create-bcp-app` can scaffold:
 
-## Storage
-
-### Local filesystem
-
-```ts
-import {
-    createLocalStorage,
-} from "bcp/server";
-
-const storage =
-    createLocalStorage({
-        directory: "./uploads",
-    });
+```text
+None
+Local Server
+Amazon S3
+Cloudflare R2
 ```
 
-`create-bcp-app --storage local` creates `lib/storage.ts` plus a visible `storage/README.md` / `.gitkeep` scaffold. Runtime objects remain ignored by Git.
+BCP's storage API supports local and S3-compatible storage, streaming reads/writes, ranges, object listing, copy/move, portable metadata, bulk deletion and S3 signed URLs.
 
-### S3 / R2 / MinIO
+Local Server projects keep a visible scaffold:
 
-```ts
-import {
-    createS3Storage,
-} from "bcp/server";
-
-const storage =
-    createS3Storage({
-        bucket: process.env.S3_BUCKET!,
-        region: process.env.S3_REGION!,
-        endpoint: process.env.S3_ENDPOINT,
-        accessKeyId: process.env.S3_ACCESS_KEY_ID,
-        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
-    });
+```text
+storage/
+├─ .gitkeep
+└─ README.md
 ```
 
-Custom endpoints and `forcePathStyle` support common S3-compatible deployments such as MinIO. Keep credentials server-only.
-
-Read more: [S3-Compatible Storage](docs/s3-storage.md)
+Runtime objects remain ignored by Git.
 
-### Streaming storage
+Guides:
 
-The stable minimum `StorageAdapter` retains its buffered API while adapters can expose optional `putStream()` and `readStream()` implementations.
-
-```ts
-import {
-    getStorageCapabilities,
-    putStorageStream,
-    readStorageStream,
-} from "bcp/server";
-```
-
-Both built-in local and S3 adapters support streaming reads/writes and byte ranges.
-
-Read more: [Storage and File Delivery](docs/storage.md)
+- [File Upload](docs/file-upload.md)
+- [Storage & File Delivery](docs/storage.md)
+- [Storage Ecosystem](docs/storage-ecosystem.md)
+- [S3-Compatible Storage](docs/s3-storage.md)
 
-### Storage Ecosystem — 0.1.27
+## Production build
 
-BCP `0.1.27` added a richer, additive object-storage API without invalidating older `StorageAdapter` implementations:
+Build:
 
-```ts
-import {
-    copyStorageObject,
-    createStorageSignedReadUrl,
-    createStorageSignedWriteUrl,
-    deleteStorageObjects,
-    getStorageEcosystemCapabilities,
-    getStorageMetadata,
-    listStorageObjects,
-    moveStorageObject,
-    setStorageMetadata,
-} from "bcp/server";
+```bash
+npm run build
 ```
 
-Listing supports prefix filtering, limits and opaque cursors. Copy and move use native adapter operations when available, with portable fallback behavior where practical. Portable user metadata is string-to-string metadata and is distinct from authorization/business state.
-
-S3-compatible storage also supports short-lived presigned direct-transfer URLs. Local storage intentionally does not emulate signed URLs.
-
-Read more: [Storage Ecosystem](docs/storage-ecosystem.md)
-
-## File delivery
+Output:
 
-`createStorageResponse()` serves local or cloud-backed objects through the same API with `GET`, `HEAD`, ETag/Last-Modified validators and single byte ranges.
-
-```ts
-import {
-    createStorageResponse,
-} from "bcp/server";
-
-return createStorageResponse(
-    request,
-    storage,
-    "documents/report.pdf"
-);
+```text
+.bcp-framework/build/
+├─ client/
+├─ public/
+└─ server/
+   └─ server.mjs
 ```
 
-Read more: [Storage and File Delivery](docs/storage.md)
-
-## Middleware, validation, errors and caching
-
-BCP includes Middleware System v2, typed validation helpers, structured HTTP errors, structured logging and response caching/revalidation.
-
-Read more:
-
-- [Middleware](docs/middleware.md)
-- [Validation](docs/validation.md)
-- [Error Handling](docs/error-handling.md)
-- [Logging and Observability](docs/development-logging.md)
-- [Caching](docs/caching.md)
-- [Security](docs/security.md)
-
-## Production build
+Run:
 
 ```bash
-npm run build
 npm run start
 ```
 
-Standalone output is written under:
+The `0.2.0` platform build target is explicitly:
 
 ```text
-.bcp-framework/build/
-├─ client/
-├─ public/
-└─ server/
-   └─ server.mjs
+standalone-node
 ```
 
-### Production Hardening — 0.1.28
+Native `.exe`, desktop and mobile compilation are not part of the `0.2.0` platform contract.
 
-The standalone runtime is wrapped by a public hardening gateway with configurable HTTP and shutdown behavior:
+Production hardening supports:
 
 ```dotenv
 BCP_REQUEST_TIMEOUT_MS=120000
@@ -384,170 +326,93 @@ BCP_SHUTDOWN_TIMEOUT_MS=10000
 BCP_TRUST_PROXY=false
 ```
 
-Standalone production handles `SIGTERM` and `SIGINT`, drains the public listener, runs application cleanup hooks and then stops internal runtime layers.
+Enable trusted proxy mode only when untrusted clients cannot bypass the trusted reverse proxy/load balancer.
 
-```ts
-import {
-    registerShutdownHook,
-} from "bcp/server";
+Read more: [Production Hardening](docs/production-hardening.md)
 
-registerShutdownHook(
-    () => {
-        storage.destroy();
-    },
-    {
-        name: "storage",
-    }
-);
-```
+## Doctor / Inspect / project metadata
 
-Trusted proxy mode is disabled by default. Enable `BCP_TRUST_PROXY=true` only when direct untrusted traffic cannot bypass the trusted reverse proxy/load balancer.
+Project diagnostics:
 
-Read more: [Production Hardening](docs/production-hardening.md)
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect --json
+```
 
-## Doctor and Inspect v2 — 0.1.29
+Doctor/Inspect v2 can report lockfile/package-manager state, duplicate framework declarations, standalone build presence, Docker/project diagnostics, storage provider and production-hardening configuration.
 
-`bcp doctor` now includes additional project/runtime diagnostics for:
+Projects created by recent `create-bcp-app` versions include non-secret scaffold metadata:
 
 ```text
-lockfile / package manager
-multiple framework dependency declarations
-standalone production artifact
-Docker + reproducible install guidance
-storage provider
-production-hardening environment validity
+bcp.project.json
 ```
 
-`bcp inspect` keeps its existing fields and adds a machine-readable `project` object with project metadata, selected presets and runtime/deployment information.
+Credentials, database passwords, access keys, JWT/session secrets and tokens must never be stored in that file.
 
-```powershell
-npm exec -- bcp-framework doctor --json
-npm exec -- bcp-framework inspect --json
-```
+Guides:
 
-Read more: [Developer Tools](docs/developer-tools.md)
+- [Developer Tools](docs/developer-tools.md)
+- [Project Metadata](docs/project-metadata.md)
 
-## Project metadata — 0.1.29
+## Updating from 0.1.x
 
-New `create-bcp-app` projects include `bcp.project.json`:
+`0.2.0` does not intentionally remove public entrypoints from the `0.1.29` baseline.
 
-```json
-{
-  "schemaVersion": 1,
-  "framework": "bcp",
-  "projectName": "my-app",
-  "packageManager": "npm",
-  "presets": {
-    "tailwind": true,
-    "database": "mysql",
-    "auth": "jwt-cookie",
-    "storage": "local"
-  }
-}
-```
+Recommended upgrade flow after publication:
 
-This file stores only non-secret scaffold metadata. Credentials, database passwords, access keys, JWT/session secrets and tokens stay in environment/server-only configuration.
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework update --check
+npm exec -- bcp-framework update 0.2.0
+npm run typecheck
+npm run build
+```
 
-Existing projects without the file continue to work; diagnostic tooling falls back to project files where practical.
+Do not reuse a standalone `.bcp-framework/build` produced by an older framework version; rebuild after upgrading.
 
-Read more: [Project Metadata](docs/project-metadata.md)
+Read more: [Migrating to 0.2.0](docs/migration-0.2.md)
 
-## Windows CLI
+## Documentation source and bcp-docs-web
 
-Microsoft SQL Server can install another executable named `bcp.exe`. BCP publishes the collision-free alias `bcp-framework`.
+The framework repository is the documentation source of truth.
 
-Inside project npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
+`bcp-docs-web` should consume:
 
-For direct PowerShell usage:
+```text
+docs/docs-web-manifest.json
+  -> navigation, routes, Markdown sources and release routes
 
-```powershell
-npm exec -- bcp-framework --version
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect
-npm exec -- bcp-framework routes
-npm exec -- bcp-framework generate page dashboard/users
-npm exec -- bcp-framework dev
-npm exec -- bcp-framework build
+docs/platform-manifest.json
+  -> version, runtime target, public entrypoints and capabilities
 ```
 
-Read more: [Developer Tools](docs/developer-tools.md)
+Markdown under `docs/` remains the authored content source.
 
-## Updating BCP
+Start here:
 
-```bash
-bcp update
-bcp update --check
-bcp update --dry-run
-bcp update 0.1.29
-bcp update next
-```
+- [Documentation Source Map](docs/README.md)
+- [Docs-Web Manifest](docs/docs-web-manifest.json)
+- [Platform Manifest](docs/platform-manifest.json)
+- [Framework Platform Contract](docs/platform-contract.md)
+- [Migration Guide](docs/migration-0.2.md)
 
-Read more: [Updating](docs/updating.md)
+## Release validation
 
-## Framework development and release validation
+Framework releases must pass:
 
 ```bash
 npm install
 npm run typecheck
 npm run test:unit
 npm run test:integration
-npm run test:e2e
 npm run test:package
+npm run test:e2e
 npm run rc:check
 ```
 
-A version must not be tagged or published until its RC and packed-package verification pass.
-
-Read more: [Releasing](docs/releasing.md)
-
-## Documentation source and `bcp-docs-web`
-
-The `docs/` directory is the authored source for **`bcp-docs-web`**.
-
-Starting with `0.1.29`, docs-web should consume:
-
-```text
-docs/docs-web-manifest.json
-```
-
-for sidebar/navigation and route mapping. Markdown files remain the documentation content source of truth.
+`0.2.0` adds a platform-contract package smoke check that verifies the prepared npm artifact's public exports, executable aliases, Node baseline, docs metadata and framework/create-app version parity.
 
-The manifest contains:
-
-```text
-section id/title
-website route
-Markdown source file
-page title
-version target
-release state
-release routes
-```
-
-Recommended starting points:
-
-- [Docs-Web Manifest](docs/docs-web-manifest.json)
-- [Documentation Source Map](docs/README.md)
-- [Getting Started](docs/getting-started.md)
-- [Configuration](docs/configuration.md)
-- [Project Metadata](docs/project-metadata.md)
-- [Routing](docs/routing.md)
-- [Project Generators](docs/generators.md)
-- [Server Data Loaders](docs/server-data-loaders.md)
-- [Route Guards](docs/route-guards.md)
-- [Form Actions](docs/form-actions.md)
-- [Server Request APIs](docs/server-request-apis.md)
-- [File Upload](docs/file-upload.md)
-- [Storage and File Delivery](docs/storage.md)
-- [Storage Ecosystem](docs/storage-ecosystem.md)
-- [S3-Compatible Storage](docs/s3-storage.md)
-- [Production Hardening](docs/production-hardening.md)
-- [Authentication](docs/authentication.md)
-- [Database](docs/database.md)
-- [Middleware](docs/middleware.md)
-- [Developer Tools](docs/developer-tools.md)
-- [Deployment](docs/deployment.md)
-- [Releasing](docs/releasing.md)
+Do not tag or publish a release until the final release commit passes the complete RC sequence.
 
 ## Release history
 
@@ -563,20 +428,13 @@ Recommended starting points:
 | `0.1.27` | Storage Ecosystem |
 | `0.1.28` | Production Hardening |
 | `0.1.29` | Developer Experience |
+| `0.2.0` | Framework Platform baseline |
 
 ## Next direction
 
-After `0.1.29`, the planned major milestone is **`0.2.0 — Framework Platform`**.
-
-The focus should be consolidation rather than unrelated feature growth:
-
-1. public API consistency and compatibility expectations,
-2. production-runtime stabilization across supported deployment paths,
-3. documentation completeness and docs-web integration,
-4. migration guidance for pre-`0.2.0` applications,
-5. a documented platform baseline for routing, data, auth, database, storage and runtime APIs.
+After the `0.2.0` platform baseline is validated and released, later `0.2.x` work can add broader build/deployment targets and higher-level platform features without changing the existing standalone Node.js contract by accident.
 
-These are roadmap goals, not `0.1.29` guarantees.
+Native executable/desktop/mobile packaging remains future roadmap work, not a `0.2.0` guarantee.
 
 ## License