@chidchanun/bcp 0.2.0 → 0.2.2

package/docs/README.md

@@ -2,23 +2,26 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.0`
+> **Documentation target:** BCP Framework `0.2.2`
 >
-> **Release state:** unreleased development target. Do not label `0.2.0` as published until RC validation, tagging and npm publication complete.
+> **Release state:** unreleased development target. Do not label `0.2.2` as published until RC validation, tagging and npm publication complete.
 
 ## Documentation architecture
 
-BCP `0.2.0` uses two machine-readable manifests:
+BCP uses three machine-readable documentation contracts:
 
 ```text
 docs/docs-web-manifest.json
-  -> website navigation, routes, Markdown sources and release pages
+  -> website navigation, routes, Markdown sources and release routes
 
 docs/platform-manifest.json
-  -> framework version, runtime target, public entrypoints and capability metadata
+  -> framework version, runtime target, public entrypoints and capabilities
+
+docs/api-manifest.json
+  -> public package entrypoints, source ownership and guide mapping
 ```
 
-Markdown files under `docs/` remain the authored content source.
+Markdown files under `docs/` remain the authored documentation content.
 
 Recommended flow:
 
@@ -28,35 +31,41 @@ framework source/tests
       docs/
         ├─ Markdown content
         ├─ docs-web-manifest.json
-        └─ platform-manifest.json
+        ├─ platform-manifest.json
+        └─ api-manifest.json
+        ↓
+manifest-driven sync
         ↓
     bcp-docs-web
 ```
 
 Framework source and tests remain authoritative for runtime behavior.
 
-## 0.2.0 Framework Platform baseline
+## 0.2.2 — Configuration & Environment v2
 
-`0.2.0` establishes an explicit compatibility/platform contract rather than introducing a new runtime architecture.
+`0.2.2` adds an optional typed application environment schema while preserving the established framework configuration precedence.
 
-New platform documents:
+New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `platform-manifest.json` | Machine-readable platform/version/public-entrypoint metadata |
-| `platform-contract.md` | Human-readable public platform contract |
-| `migration-0.2.md` | Upgrade guide from the `0.1.x` baseline |
-| `releases/0.2.0.md` | Release notes for the milestone |
+| `environment-validation.md` | `bcp.environment.*`, validation rules, CLI checks and secret/public boundaries |
+| `configuration.md` | Framework configuration precedence and diagnostics workflow |
+| `platform-manifest.json` | Declares typed environment/config diagnostics capabilities |
+| `api-manifest.json` | Maps `bcp/config` to configuration and environment guides |
+| `releases/0.2.2.md` | Configuration & Environment v2 release notes |
 
-Compatibility intent from `0.1.29`:
+Primary command:
 
-```text
-intentional public-entrypoint removals: none
-standalone runtime model change: none
-supported production build target: standalone-node
+```bash
+bcp config check
 ```
 
-BCP remains pre-1.0, so application upgrades should still be validated before production deployment.
+JSON diagnostics:
+
+```bash
+bcp config check --json
+```
 
 ## Update rule
 
@@ -65,12 +74,13 @@ When framework behavior or public surface changes:
 1. Update framework source.
 2. Add/update regression tests.
 3. Update the matching Markdown guide.
-4. Update `platform-manifest.json` when public entrypoints/runtime/capability metadata changes.
-5. Update `docs-web-manifest.json` when website navigation/routes change.
-6. Update `docs/releases/<version>.md`.
-7. Change release state to published only after npm publication succeeds.
+4. Update `platform-manifest.json` when runtime/public-entrypoint/capability metadata changes.
+5. Update `api-manifest.json` when public API ownership/guide mapping changes.
+6. Update `docs-web-manifest.json` when website routes/navigation change.
+7. Update `docs/releases/<version>.md`.
+8. Change release state only after the release workflow reaches that state.
 
-## Current docs-web navigation
+## Docs-web navigation
 
 `docs/docs-web-manifest.json` is the authoritative ordered navigation contract.
 
@@ -85,105 +95,110 @@ Runtime & Infrastructure
 Storage & Uploads
 Developer Experience
 Platform & Compatibility
+API Reference
 Releases
 ```
 
-### Getting Started
+Important current routes:
 
 | Website route | Markdown source |
 | --- | --- |
-| `/docs/getting-started` | `getting-started.md` |
 | `/docs/configuration` | `configuration.md` |
-| `/docs/application-modules` | `application-modules.md` |
-| `/docs/project-metadata` | `project-metadata.md` |
-| `/docs/deployment` | `deployment.md` |
-| `/docs/updating` | `updating.md` |
+| `/docs/environment-validation` | `environment-validation.md` |
+| `/docs/platform-contract` | `platform-contract.md` |
+| `/docs/documentation-platform` | `documentation-platform.md` |
+| `/docs/migration-0.2` | `migration-0.2.md` |
+| `/docs/api-reference` | `api-reference.md` |
+| `/releases/0.2.2` | `releases/0.2.2.md` |
 
-### Routing & Data
+Every route/source pair is validated by unit tests.
 
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/routing` | `routing.md` |
-| `/docs/server-data-loaders` | `server-data-loaders.md` |
-| `/docs/route-guards` | `route-guards.md` |
-| `/docs/form-actions` | `form-actions.md` |
-| `/docs/server-request-apis` | `server-request-apis.md` |
-| `/docs/validation` | `validation.md` |
-| `/docs/error-handling` | `error-handling.md` |
+## Configuration source model
 
-### Authentication
+Framework settings:
 
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/authentication` | `authentication.md` |
-| `/docs/auth-route-guards` | `auth-route-guards.md` |
-| `/docs/session-auth` | `session-auth.md` |
+```text
+bcp.config.ts
+bcp.config.mts
+bcp.config.js
+bcp.config.mjs
+```
 
-### Database
+Application environment schema:
 
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/database` | `database.md` |
-| `/docs/database-migrations` | `database-migrations.md` |
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
+```
 
-### Runtime & Infrastructure
+Only one file from each convention may exist at a time.
 
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/middleware` | `middleware.md` |
-| `/docs/hydration` | `hydration.md` |
-| `/docs/development-logging` | `development-logging.md` |
-| `/docs/caching` | `caching.md` |
-| `/docs/security` | `security.md` |
-| `/docs/production-hardening` | `production-hardening.md` |
+The environment schema is optional. Existing applications without `bcp.environment.*` continue to use the previous environment-loading behavior.
 
-### Storage & Uploads
+Configuration precedence remains:
 
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/file-upload` | `file-upload.md` |
-| `/docs/storage` | `storage.md` |
-| `/docs/storage-ecosystem` | `storage-ecosystem.md` |
-| `/docs/s3-storage` | `s3-storage.md` |
+```text
+CLI override
+    ↓
+BCP_* environment
+    ↓
+bcp.config.*
+    ↓
+framework defaults
+```
 
-### Developer Experience
+See [Environment Validation](environment-validation.md).
 
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/generators` | `generators.md` |
-| `/docs/developer-tools` | `developer-tools.md` |
+## Environment security boundary
 
-### Platform & Compatibility
+`BCP_PUBLIC_*` values may be embedded into browser bundles. They must never contain credentials/private secrets.
 
-| Website route | Markdown source |
-| --- | --- |
-| `/docs/platform-contract` | `platform-contract.md` |
-| `/docs/migration-0.2` | `migration-0.2.md` |
+A variable declared with:
 
-## Platform manifest
+```ts
+secret: true
+```
 
-`docs/platform-manifest.json` is intended for tooling and `bcp-docs-web` metadata displays.
+must not use the `BCP_PUBLIC_` prefix. The configuration validator treats that combination as an error.
 
-It records:
+`secret: true` is validation/tooling metadata and does not encrypt a value.
+
+## Platform manifest
+
+`docs/platform-manifest.json` describes the supported framework baseline, including:
 
 ```text
-schema version
-framework/version/release state
+framework version/release state
 Node/React/runtime baseline
 production build target
 public package entrypoints
 CLI command families
-capability groups
-storage-provider families
+capability flags
 previous-baseline compatibility intent
 documentation contract files
 ```
 
-Do not treat the manifest as executable runtime configuration. It describes the supported platform surface; framework source/tests remain authoritative.
+`0.2.2` declares the additional capabilities:
+
+```text
+typedEnvironmentSchema
+configurationDiagnostics
+configCheckCli
+```
+
+The supported production target remains:
+
+```text
+standalone-node
+```
+
+## API manifest
 
-## Public entrypoint baseline
+`docs/api-manifest.json` describes the public package entrypoints documentation tooling may present as supported API surfaces.
 
-The `0.2.0` platform recognizes:
+Current entrypoints:
 
 ```text
 bcp
@@ -199,151 +214,40 @@ bcp/server-only
 bcp/middleware
 ```
 
-`bcp-docs-web` can use this list to build an API-reference index without hard-coding a second entrypoint list.
-
-## API guide ownership
-
-| Entrypoint | Primary guides |
-| --- | --- |
-| `bcp` | `routing.md`, `server-data-loaders.md`, `form-actions.md` |
-| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `production-hardening.md` |
-| `bcp/auth` | `authentication.md`, `auth-route-guards.md`, `session-auth.md` |
-| `bcp/database` | `database.md`, `database-migrations.md` |
-| `bcp/validation` | `validation.md` |
-| `bcp/error` | `error-handling.md` |
-| `bcp/cache` | `caching.md` |
-| `bcp/config` | `configuration.md` |
-| `bcp/middleware` | `middleware.md` |
-
-## Current capability groups
-
-### Application
-
-- React SSR/hydration
-- file-based page/API routing
-- dynamic/catch-all/optional catch-all routes
-- layouts/metadata/route groups
-- SPA navigation
-- loaders/guards/form actions
-- client islands / partial hydration
-
-### Server/runtime
-
-- request-scoped server APIs
-- JWT cookie sessions
-- Middleware System v2
-- validation and structured HTTP errors
-- structured logging/request IDs
-- response caching/revalidation
-- production hardening/timeouts
-- graceful shutdown and shutdown hooks
-- trusted-proxy controls
-
-### Database
-
-- MySQL framework primitives
-- prepared query/execute helpers
-- transactions
-- migrations/status/rollback
-
-### Storage & uploads
-
-- buffered multipart APIs
-- streaming multipart upload
-- local filesystem storage
-- Amazon S3 / Cloudflare R2 / S3-compatible storage
-- streaming reads/writes and byte ranges
-- list/copy/move
-- portable metadata
-- bulk delete
-- S3 signed read/write URLs
-
-### Developer Experience
-
-- `create-bcp-app`
-- Local / Amazon S3 / Cloudflare R2 storage presets
-- non-secret `bcp.project.json`
-- page/API/middleware/migration generators
-- Doctor/Inspect v2
-- framework updater
-- Windows-safe `bcp-framework` alias
-
-## Build/runtime baseline
-
-Supported `0.2.0` production target:
-
-```text
-standalone-node
-```
-
-Build output:
+`bcp/config` owns both:
 
 ```text
-.bcp-framework/build/
-├─ client/
-├─ public/
-└─ server/
-   └─ server.mjs
+/docs/configuration
+/docs/environment-validation
 ```
 
-Native executable, desktop and mobile compilation are not part of the `0.2.0` platform contract.
-
-## Releases
+The API-manifest entrypoint set must match the platform public-entrypoint set exactly.
 
-Release notes live in:
+## bcp-docs-web synchronization
 
-```text
-docs/releases/
-```
-
-Current manifest routes begin with:
+The docs website sync loads the manifests before Markdown content:
 
 ```text
-/releases/0.2.0
-/releases/0.1.29
-/releases/0.1.28
-/releases/0.1.27
-/releases/0.1.26
-```
-
-Use release states consistently:
-
-```text
-published
-release candidate
-unreleased development target
-```
-
-The presence of a release note does not mean the npm version is published.
-
-## Suggested bcp-docs-web implementation
-
-At build/startup:
-
-```text
-load docs-web-manifest.json
-load platform-manifest.json
+selected framework ref
         ↓
-validate schema/version relationship
+docs-web-manifest.json
+platform-manifest.json
+api-manifest.json
         ↓
-build sidebar + route map + release map
+validate version/release/API parity
         ↓
 load referenced Markdown
         ↓
-render content + prev/next + search index
-        ↓
-show version/release/platform metadata
+synchronize CMS/search/navigation
 ```
 
-Recommended website behavior:
+Examples from the docs-web project:
 
-1. Build navigation in manifest order.
-2. Resolve every website route to its Markdown source.
-3. Generate previous/next links from manifest ordering.
-4. Use `versionTarget` and `releaseState` for banners.
-5. Use `platform-manifest.json` for runtime/public-entrypoint metadata.
-6. Index Markdown headings/content for search.
-7. Never ingest runtime `.env` files into public documentation output.
+```powershell
+npm run docs:sync -- --dry-run
+npm run docs:sync -- --publish-new
+npm run docs:sync -- --ref=v0.2.1
+```
 
 ## Source conventions
 
@@ -354,11 +258,12 @@ Recommended website behavior:
 - exact public API names,
 - clear stable/RC/roadmap labels,
 - security limitations next to affected APIs,
-- no framework-internal module presented as public API.
+- no framework-internal module presented as public API,
+- no secrets/runtime `.env` values in public documentation metadata.
 
 ## Release validation
 
-Before publishing `0.2.0`:
+Before publishing `0.2.2`:
 
 ```bash
 npm run typecheck
@@ -369,28 +274,19 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.0` adds a platform-contract package smoke check that verifies:
+Configuration & Environment v2 validation covers:
 
-- prepared framework/create-app version parity,
-- required public exports,
-- both CLI executable aliases,
-- Node.js engine baseline,
-- inclusion of platform/docs contract files,
-- docs-web target/version consistency.
+- typed environment rules/defaults,
+- project `bcp.environment.*` loading,
+- public/secret safety boundary,
+- production diagnostics,
+- `bcp config check` CLI parsing,
+- dev schema watching,
+- public `bcp/config` exports,
+- prepared npm package files,
+- docs/platform/API version parity.
 
-The final release tag must point to the commit that passed the complete RC sequence.
-
-## Documentation QA checklist
-
-- every manifest Markdown source exists,
-- every website route is unique,
-- docs-web target matches platform version,
-- platform public entrypoints match package exports,
-- examples use public APIs/commands,
-- release states are accurate,
-- secrets are never placed in project/docs metadata,
-- proxy trust remains opt-in,
-- roadmap features are not presented as release guarantees.
+The final release tag must point to the exact commit that passed the complete RC sequence.
 
 ## Repository authority
 
@@ -403,7 +299,24 @@ tests
 Markdown docs
 docs-web manifest
 platform manifest
+API manifest
 release notes
 ```
 
-`bcp-docs-web` is the presentation/search/navigation layer for this content.
+`bcp-docs-web` remains the presentation/search/navigation layer for this content.
+
+## Next direction
+
+Planned next milestone:
+
+```text
+0.2.3 — Database Platform v2
+```
+
+Focus:
+
+- database adapter contract,
+- PostgreSQL support,
+- SQLite support,
+- connection lifecycle improvements,
+- provider-consistent migration workflows.

package/docs/api-manifest.json

@@ -0,0 +1,130 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "version": "0.2.2",
+  "releaseState": "unreleased",
+  "coverage": "public-entrypoints",
+  "entrypoints": [
+    {
+      "package": "bcp",
+      "source": "packages/client/src/index.tsx",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp",
+      "summary": "React application APIs for routing, links, forms, loader/guard data, islands, metadata and route error handling.",
+      "guides": [
+        "/docs/routing",
+        "/docs/server-data-loaders",
+        "/docs/route-guards",
+        "/docs/form-actions"
+      ]
+    },
+    {
+      "package": "bcp/island",
+      "source": "packages/client/src/islands.tsx",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-island",
+      "summary": "Partial-hydration island creation and island loading strategy types.",
+      "guides": [
+        "/docs/hydration"
+      ]
+    },
+    {
+      "package": "bcp/cache",
+      "source": "packages/client/src/cache.ts",
+      "environment": "server-preferred",
+      "route": "/docs/api-reference#bcp-cache",
+      "summary": "Cache, deduplication, statistics and path/tag revalidation primitives.",
+      "guides": [
+        "/docs/caching"
+      ]
+    },
+    {
+      "package": "bcp/config",
+      "source": "packages/client/src/config.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-config",
+      "summary": "Typed BCP configuration, environment-schema validation and configuration diagnostics APIs.",
+      "guides": [
+        "/docs/configuration",
+        "/docs/environment-validation"
+      ]
+    },
+    {
+      "package": "bcp/validation",
+      "source": "packages/client/src/validation.ts",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-validation",
+      "summary": "Typed validators, parse helpers and structured validation errors.",
+      "guides": [
+        "/docs/validation"
+      ]
+    },
+    {
+      "package": "bcp/error",
+      "source": "packages/client/src/http-error.ts",
+      "environment": "universal",
+      "route": "/docs/api-reference#bcp-error",
+      "summary": "Structured HTTP error creation, classification and response helpers.",
+      "guides": [
+        "/docs/error-handling"
+      ]
+    },
+    {
+      "package": "bcp/database",
+      "source": "packages/client/src/database.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-database",
+      "summary": "Database pool, prepared query/execute helpers and transaction primitives.",
+      "guides": [
+        "/docs/database",
+        "/docs/database-migrations"
+      ]
+    },
+    {
+      "package": "bcp/auth",
+      "source": "packages/client/src/auth.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-auth",
+      "summary": "Authentication, login/logout/session rotation and route authorization guards.",
+      "guides": [
+        "/docs/authentication",
+        "/docs/auth-route-guards",
+        "/docs/session-auth"
+      ]
+    },
+    {
+      "package": "bcp/server",
+      "source": "packages/client/src/server.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-server",
+      "summary": "Request context, cookies, logging, production hardening, upload, storage, response and session APIs.",
+      "guides": [
+        "/docs/server-request-apis",
+        "/docs/file-upload",
+        "/docs/storage",
+        "/docs/storage-ecosystem",
+        "/docs/production-hardening"
+      ]
+    },
+    {
+      "package": "bcp/server-only",
+      "source": "packages/client/src/server-only.mjs",
+      "environment": "server-marker",
+      "route": "/docs/api-reference#bcp-server-only",
+      "summary": "Server-only module boundary marker that prevents accidental browser inclusion.",
+      "guides": [
+        "/docs/application-modules"
+      ]
+    },
+    {
+      "package": "bcp/middleware",
+      "source": "packages/server/src/middleware.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-middleware",
+      "summary": "Middleware System v2 request/response pipeline types and helpers.",
+      "guides": [
+        "/docs/middleware"
+      ]
+    }
+  ]
+}