@chidchanun/bcp 0.1.29 → 0.2.1

package/README.md

@@ -1,10 +1,36 @@
 # 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.1 — Documentation 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.1` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+
+## 0.2 platform
+
+`0.2.0` established the Framework Platform baseline. `0.2.1` builds a machine-readable Documentation Platform on top of that baseline without intentionally removing application runtime public entrypoints.
+
+The authoritative platform/documentation contracts are:
+
+```text
+docs/platform-manifest.json
+  -> runtime target, public entrypoints, capabilities and compatibility
+
+docs/docs-web-manifest.json
+  -> docs sections, routes, Markdown sources and releases
+
+docs/api-manifest.json
+  -> public package entrypoints, source ownership and guide routes
+```
+
+Authored documentation remains under `docs/*.md`.
+
+Read more:
+
+- [Framework Platform Contract](docs/platform-contract.md)
+- [Documentation Platform](docs/documentation-platform.md)
+- [API Reference](docs/api-reference.md)
+- [Migrating to 0.2.x](docs/migration-0.2.md)
 
 ## Current capabilities
 
@@ -12,29 +38,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 |
+| Validation | Typed validators 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 | Manifest-driven docs navigation, platform metadata and public API entrypoint reference |
 
 ## 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 +70,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 +98,7 @@ React SSR
 Hydration / SPA navigation
 ```
 
-A route can keep page, loader, guard and actions together:
+Typical route structure:
 
 ```text
 app/
@@ -98,73 +116,104 @@ app/
       └─ route.ts
 ```
 
-## Routing
+## Public entrypoints
 
-Page routes are discovered from `app/**/page.tsx` and API routes from `app/**/route.ts`.
+The `0.2.x` platform contract recognizes:
 
 ```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 these public package entrypoints rather than importing internal framework files under `packages/`.
+
+The public list is validated in both:
+
+- [Platform Manifest](docs/platform-manifest.json)
+- [API Manifest](docs/api-manifest.json)
+
+See [API Reference](docs/api-reference.md) for ownership and related guides.
+
+## 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 project-local collision-free 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.
-
-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 +234,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,168 +248,42 @@ 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.
-
-Read more: [File Upload](docs/file-upload.md)
-
-## Storage
-
-### Local filesystem
-
-```ts
-import {
-    createLocalStorage,
-} from "bcp/server";
-
-const storage =
-    createLocalStorage({
-        directory: "./uploads",
-    });
-```
-
-`create-bcp-app --storage local` creates `lib/storage.ts` plus a visible `storage/README.md` / `.gitkeep` scaffold. Runtime objects remain ignored by Git.
-
-### S3 / R2 / MinIO
-
-```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,
-    });
-```
-
-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)
-
-### Streaming storage
-
-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)
-
-### Storage Ecosystem — 0.1.27
-
-BCP `0.1.27` added a richer, additive object-storage API without invalidating older `StorageAdapter` implementations:
-
-```ts
-import {
-    copyStorageObject,
-    createStorageSignedReadUrl,
-    createStorageSignedWriteUrl,
-    deleteStorageObjects,
-    getStorageEcosystemCapabilities,
-    getStorageMetadata,
-    listStorageObjects,
-    moveStorageObject,
-    setStorageMetadata,
-} from "bcp/server";
-```
-
-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.
+## Storage and uploads
 
-S3-compatible storage also supports short-lived presigned direct-transfer URLs. Local storage intentionally does not emulate signed URLs.
+`create-bcp-app` can scaffold:
 
-Read more: [Storage Ecosystem](docs/storage-ecosystem.md)
-
-## File delivery
-
-`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
+None
+Local Server
+Amazon S3
+Cloudflare R2
 ```
 
-Read more: [Storage and File Delivery](docs/storage.md)
-
-## Middleware, validation, errors and caching
+BCP storage supports local and S3-compatible adapters, streaming reads/writes, ranges, object listing, copy/move, portable metadata, bulk deletion and S3 signed URLs.
 
-BCP includes Middleware System v2, typed validation helpers, structured HTTP errors, structured logging and response caching/revalidation.
+Guides:
 
-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)
+- [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)
 
 ## Production build
 
+Build:
+
 ```bash
 npm run build
-npm run start
 ```
 
-Standalone output is written under:
+Output:
 
 ```text
 .bcp-framework/build/
@@ -372,211 +293,129 @@ Standalone output is written under:
    └─ server.mjs
 ```
 
-### Production Hardening — 0.1.28
+Run:
 
-The standalone runtime is wrapped by a public hardening gateway with configurable HTTP and shutdown behavior:
-
-```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
+```bash
+npm run start
 ```
 
-Standalone production handles `SIGTERM` and `SIGINT`, drains the public listener, runs application cleanup hooks and then stops internal runtime layers.
+The `0.2.x` production target remains:
 
-```ts
-import {
-    registerShutdownHook,
-} from "bcp/server";
-
-registerShutdownHook(
-    () => {
-        storage.destroy();
-    },
-    {
-        name: "storage",
-    }
-);
+```text
+standalone-node
 ```
 
-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.
+Native `.exe`, desktop and mobile compilation are future roadmap work and are not part of the current platform contract.
 
-Read more: [Production Hardening](docs/production-hardening.md)
+Production hardening supports configurable request/header/keep-alive/shutdown timeouts, trusted-proxy handling and `SIGTERM` / `SIGINT` graceful shutdown.
 
-## Doctor and Inspect v2 — 0.1.29
+Read more: [Production Hardening](docs/production-hardening.md)
 
-`bcp doctor` now includes additional project/runtime diagnostics for:
+## Documentation Platform — 0.2.1
 
-```text
-lockfile / package manager
-multiple framework dependency declarations
-standalone production artifact
-Docker + reproducible install guidance
-storage provider
-production-hardening environment validity
-```
+`0.2.1` makes the framework repository directly consumable by `bcp-docs-web`.
 
-`bcp inspect` keeps its existing fields and adds a machine-readable `project` object with project metadata, selected presets and runtime/deployment information.
+Recommended website flow:
 
-```powershell
-npm exec -- bcp-framework doctor --json
-npm exec -- bcp-framework inspect --json
+```text
+selected framework ref
+        ↓
+docs/docs-web-manifest.json
+docs/platform-manifest.json
+docs/api-manifest.json
+        ↓
+validate version + release state + public entrypoints
+        ↓
+load referenced Markdown
+        ↓
+sync CMS/search/navigation
+        ↓
+render bcp-docs-web
 ```
 
-Read more: [Developer Tools](docs/developer-tools.md)
+`bcp-docs-web` should not maintain a second hard-coded framework page list.
 
-## Project metadata — 0.1.29
+The manifests provide:
 
-New `create-bcp-app` projects include `bcp.project.json`:
-
-```json
-{
-  "schemaVersion": 1,
-  "framework": "bcp",
-  "projectName": "my-app",
-  "packageManager": "npm",
-  "presets": {
-    "tailwind": true,
-    "database": "mysql",
-    "auth": "jwt-cookie",
-    "storage": "local"
-  }
-}
+```text
+sidebar/category order
+website routes
+Markdown sources
+version + release state
+release routes
+public package entrypoints
+API guide ownership
 ```
 
-This file stores only non-secret scaffold metadata. Credentials, database passwords, access keys, JWT/session secrets and tokens stay in environment/server-only configuration.
+The docs sync may target a release ref for historical content:
 
-Existing projects without the file continue to work; diagnostic tooling falls back to project files where practical.
+```powershell
+npm run docs:sync -- --ref=v0.2.0
+```
 
-Read more: [Project Metadata](docs/project-metadata.md)
+Read more:
 
-## Windows CLI
+- [Documentation Platform](docs/documentation-platform.md)
+- [Documentation Source Map](docs/README.md)
+- [Docs-Web Manifest](docs/docs-web-manifest.json)
+- [Platform Manifest](docs/platform-manifest.json)
+- [API Manifest](docs/api-manifest.json)
 
-Microsoft SQL Server can install another executable named `bcp.exe`. BCP publishes the collision-free alias `bcp-framework`.
+## Updating from 0.1.x / 0.2.x
 
-Inside project npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
+`0.2.1` does not intentionally remove application public entrypoints from the `0.2.0` baseline.
 
-For direct PowerShell usage:
+After upgrading, always rebuild the standalone artifact instead of reusing `.bcp-framework/build` from another framework version.
 
-```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
-```
+Read more: [Migrating to 0.2.x](docs/migration-0.2.md)
 
-Read more: [Developer Tools](docs/developer-tools.md)
+## Release validation
 
-## Updating BCP
-
-```bash
-bcp update
-bcp update --check
-bcp update --dry-run
-bcp update 0.1.29
-bcp update next
-```
-
-Read more: [Updating](docs/updating.md)
-
-## 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.1` adds Documentation Platform unit/package checks that validate manifest version parity, docs source existence, API/public-entrypoint parity and prepared npm documentation artifacts.
 
-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
 
 | Version | Milestone |
 | --- | --- |
-| `0.1.20` | Hydration line-ending stabilization |
-| `0.1.21` | Hydration semantic parity |
-| `0.1.22` | Developer tools and diagnostics |
-| `0.1.23` | Logging and observability |
 | `0.1.24` | File Upload Foundation |
 | `0.1.25` | Storage Adapters and File Delivery |
 | `0.1.26` | S3-Compatible Storage and Production Streaming |
 | `0.1.27` | Storage Ecosystem |
 | `0.1.28` | Production Hardening |
 | `0.1.29` | Developer Experience |
+| `0.2.0` | Framework Platform |
+| `0.2.1` | Documentation Platform |
 
-## Next direction
+## Roadmap
 
-After `0.1.29`, the planned major milestone is **`0.2.0 — Framework Platform`**.
+Next planned milestone:
+
+```text
+0.2.2 — Configuration & Environment v2
+```
 
-The focus should be consolidation rather than unrelated feature growth:
+Focus:
 
-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.
+- typed production configuration improvements,
+- environment validation,
+- startup configuration diagnostics,
+- configuration schema/inspection tooling.
 
-These are roadmap goals, not `0.1.29` guarantees.
+Application packaging (`bcp package`, native executable experiments) remains later `0.2.x` roadmap work.
 
 ## License