@chidchanun/bcp 0.1.24 → 0.1.26

package/docs/README.md

@@ -1,89 +1,169 @@
 # BCP Framework Documentation Source
 
-This directory is the documentation source of truth for the BCP Framework documentation website (`bcp-docs`).
+The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized for the future **`bcp-docs-web`** website.
 
-> Documentation target: BCP Framework `0.1.24`
+> **Documentation target:** BCP Framework `0.1.26`
+>
+> **Release state:** release-candidate source. Do not label `0.1.26` as published until RC validation and npm publication complete.
 
-When framework behavior changes, update framework source/tests first, then the matching file under `docs/`, then the release note under `docs/releases/`.
+## Documentation flow
 
-## Recommended website navigation
+```text
+BCP Framework source/tests
+        ↓
+      docs/
+        ↓
+   bcp-docs-web
+```
+
+Framework source and tests are authoritative for behavior. Markdown under `docs/` is the authored documentation layer. `bcp-docs-web` should render, organize and search these sources instead of becoming a competing source of truth.
+
+## Update rule
+
+When framework behavior changes:
+
+1. Update framework source.
+2. Add/update regression tests.
+3. Update the matching file under `docs/`.
+4. Update `docs/releases/<version>.md`.
+5. Change release state to published only after npm publication succeeds.
+
+## Recommended `bcp-docs-web` navigation
+
+```text
+Getting Started
+Routing & Data
+Authentication
+Database
+Runtime & Infrastructure
+Storage & Uploads
+API Reference
+Releases
+```
 
 ### Getting Started
 
-| Route | Source | Purpose |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
 | `/docs/getting-started` | `getting-started.md` | Create and run a BCP application |
-| `/docs/configuration` | `configuration.md` | Framework configuration |
+| `/docs/configuration` | `configuration.md` | Framework configuration/environment |
 | `/docs/application-modules` | `application-modules.md` | Client/server boundaries |
-| `/docs/deployment` | `deployment.md` | Production deployment |
+| `/docs/deployment` | `deployment.md` | Standalone production deployment |
 | `/docs/updating` | `updating.md` | Framework upgrades |
 
-### Routing and Data
+### Routing & Data
 
-| Route | Source | Purpose |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
-| `/docs/routing` | `routing.md` | File-based routing |
+| `/docs/routing` | `routing.md` | File-based page/API routing |
 | `/docs/server-data-loaders` | `server-data-loaders.md` | Server-side page data |
 | `/docs/route-guards` | `route-guards.md` | Scoped route authorization |
 | `/docs/form-actions` | `form-actions.md` | Server mutations/forms |
 | `/docs/server-request-apis` | `server-request-apis.md` | Request/cookie/response APIs |
 | `/docs/validation` | `validation.md` | Typed validation |
 | `/docs/error-handling` | `error-handling.md` | Structured HTTP errors |
-| `/docs/file-upload` | `file-upload.md` | Multipart parsing, validation and local file storage |
 
 ### Authentication
 
-| Route | Source | Purpose |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
 | `/docs/authentication` | `authentication.md` | Authentication Core |
-| `/docs/auth-route-guards` | `auth-route-guards.md` | Auth-aware guards |
+| `/docs/auth-route-guards` | `auth-route-guards.md` | Auth-aware route guards |
 | `/docs/session-auth` | `session-auth.md` | JWT cookie sessions |
 
 ### Database
 
-| Route | Source | Purpose |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
 | `/docs/database` | `database.md` | MySQL database primitives |
-| `/docs/database-migrations` | `database-migrations.md` | Migration CLI and files |
+| `/docs/database-migrations` | `database-migrations.md` | Migration CLI/files |
 
-### Runtime and Infrastructure
+### Runtime & Infrastructure
 
-| Route | Source | Purpose |
+| Website route | Markdown source | Purpose |
 | --- | --- | --- |
 | `/docs/middleware` | `middleware.md` | Middleware System v2 |
 | `/docs/hydration` | `hydration.md` | SSR/client hydration parity |
-| `/docs/developer-tools` | `developer-tools.md` | `doctor` / `inspect` diagnostics |
-| `/docs/development-logging` | `development-logging.md` | Structured logging and observability |
+| `/docs/developer-tools` | `developer-tools.md` | `doctor` / `inspect` |
+| `/docs/development-logging` | `development-logging.md` | Logging/observability |
 | `/docs/caching` | `caching.md` | Cache/revalidation |
-| `/docs/security` | `security.md` | Security defaults and body limits |
+| `/docs/security` | `security.md` | Security/body limits |
+
+### Storage & Uploads
+
+| Website route | Markdown source | Purpose |
+| --- | --- | --- |
+| `/docs/file-upload` | `file-upload.md` | Buffered + streaming multipart uploads |
+| `/docs/storage` | `storage.md` | StorageAdapter, streaming and file delivery |
+| `/docs/s3-storage` | `s3-storage.md` | S3-compatible adapter/configuration |
+
+## API Reference ownership
+
+Recommended entrypoint groups:
+
+```text
+bcp
+bcp/server
+bcp/auth
+bcp/database
+bcp/validation
+bcp/error
+bcp/cache
+bcp/config
+bcp/middleware
+```
+
+| Entrypoint | Primary guide |
+| --- | --- |
+| `bcp` | `routing.md`, `server-data-loaders.md`, `form-actions.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `s3-storage.md`, `development-logging.md` |
+| `bcp/auth` | `authentication.md`, `auth-route-guards.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 and hydration
+- React SSR/hydration
 - file-based page/API routing
-- dynamic/catch-all routes
-- layouts and metadata
+- static/dynamic/catch-all/optional-catch-all routes
+- route groups/layouts/metadata
 - SPA navigation
-- loaders, guards and form actions
+- loaders/guards/form actions
 - client islands / partial hydration
-- Fast Refresh and deterministic development hydration
+- Fast Refresh
 
 ### Server
 
-- request-scoped server APIs
-- cookies and redirects
-- JWT sessions and authentication
+- request-scoped APIs/cookies/redirects/request IDs
+- JWT sessions/authentication
 - Middleware System v2
-- typed validation and structured errors
-- structured logging with request identity
-- multipart file uploads and local filesystem persistence
+- validation/structured errors
+- structured logging
+- response caching/security gateway
+
+### Storage & Uploads
+
+- buffered multipart `FormData` upload APIs
+- production streaming multipart upload (`storeMultipartFile()`)
+- `StorageAdapter` contract
+- local filesystem adapter
+- S3-compatible adapter
+- streaming reads/writes
+- byte ranges
+- ETag/Last-Modified file delivery
+- upload/storage limits and abort cleanup
 
 ### Database
 
 - `bcp/database`
-- MySQL pool/query helpers
+- lazy MySQL pool
+- prepared execution/query helpers
 - transactions
 - migrations/status/rollback
 
@@ -93,69 +173,70 @@ When framework behavior changes, update framework source/tests first, then the m
 - `bcp update`
 - `bcp doctor`
 - `bcp inspect`
-- `bcp-framework` Windows-safe CLI alias
+- Windows-safe `bcp-framework` alias
 - standalone production build
-- release/package smoke checks
+- unit/integration/E2E/package/RC checks
 
-## BCP 0.1.24 documentation priorities
+## BCP 0.1.26 documentation focus
 
-### File Upload
+### Storage streaming
 
-BCP 0.1.24 exposes upload helpers through the server-only `bcp/server` entrypoint:
+Public additions include:
 
 ```ts
 import {
-    parseMultipartFormData,
-    getUploadedFile,
-    requireUploadedFile,
-    validateUploadedFile,
-    saveUploadedFile,
-    sanitizeUploadFileName,
-    UploadError,
+    getStorageCapabilities,
+    putStorageStream,
+    readStorageStream,
 } from "bcp/server";
 ```
 
-Documentation must make the following boundaries clear:
-
-- `server.bodyLimit` / `BCP_BODY_LIMIT` is the outer request-size limit enforced by the security gateway.
-- multipart and individual file limits can be stricter than the global body limit.
-- MIME type and extension are metadata checks, not file-signature verification.
-- default storage names are UUID based.
-- existing files are not overwritten unless explicitly requested.
-- saved metadata includes SHA-256 checksum.
-- local filesystem storage is the initial foundation; distributed/object storage requires a later adapter layer.
-
-See `file-upload.md`.
-
-### Dev route/client bundle synchronization
+Streaming methods remain optional on custom adapters for `0.1.25` compatibility.
 
-0.1.24 also fixes a development-only graph drift that could produce:
+### S3-compatible storage
 
-```text
-Client bundle was not found for route "/docs/[...slug]".
+```ts
+import {
+    createS3Storage,
+} from "bcp/server";
 ```
 
-The dev gateway now compares the actual page route topology and refreshes the internal client bundler when pathname/page/layout structure changes. Users should no longer need to manually delete `.bcp-framework` to recover a missing route bundle.
+Document:
 
-### Logging & Observability
+- bucket/region/endpoint setup,
+- optional explicit credentials,
+- AWS default credential chain behavior,
+- `forcePathStyle` for compatible services such as MinIO,
+- prefix handling,
+- multipart streaming,
+- ranges/ETag metadata,
+- overwrite limitations for concurrent multipart writers,
+- server-only credential/security requirements.
 
-0.1.23 introduced:
+See `s3-storage.md`.
 
-- `logger` / `createLogger()`
-- request-scoped `requestLogger()`
-- log levels and JSON format
-- `X-Request-Id` helpers
-- structured development request/SSR timing
+### Production multipart streaming
 
-See `development-logging.md`.
+```ts
+import {
+    storeMultipartFile,
+} from "bcp/server";
+```
 
-### Developer Tools
+Document:
 
-0.1.22 introduced `bcp doctor` and `bcp inspect`, JSON reports, duplicate React diagnostics and duplicate BCP-install protection.
+- one named streamed file field per operation,
+- total request limit,
+- per-file limit,
+- MIME/extension validation,
+- fixed/callback storage keys,
+- AbortSignal behavior,
+- direct local/S3 streaming,
+- difference from `request.formData()` / buffered APIs.
 
-See `developer-tools.md`.
+See `file-upload.md`.
 
-## Commands
+## CLI commands
 
 ```bash
 bcp dev
@@ -175,40 +256,151 @@ bcp db status
 bcp db rollback
 ```
 
-On Windows systems where SQL Server owns `bcp.exe`, direct shell commands can use:
+On Windows, direct project-local commands should prefer:
 
 ```powershell
-bcp-framework doctor
-bcp-framework inspect
-bcp-framework dev
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
 ```
 
+Inside npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
+
 ## Releases
 
-Recommended release routes:
+Release notes live under:
 
 ```text
+docs/releases/
+```
+
+Recommended routes:
+
+```text
+/releases/0.1.26
+/releases/0.1.25
 /releases/0.1.24
 /releases/0.1.23
 /releases/0.1.22
-/releases/0.1.21
-/releases/0.1.20
 ```
 
-Do not present unreleased `main` behavior as already available from npm. The website should distinguish the stable npm version from the documentation target when they differ.
+Use one of these release states:
+
+```text
+published
+release candidate
+unreleased development target
+```
+
+The existence of a release note alone does not mean the npm version is published.
+
+## Suggested website model
+
+```ts
+interface DocPage {
+    title: string;
+    slug: string;
+    section: string;
+    sourceFile: string;
+    versionTarget?: string;
+    releaseState?:
+        | "published"
+        | "rc"
+        | "unreleased";
+}
+```
+
+The first `bcp-docs-web` implementation can keep this mapping in a route manifest and consume Markdown directly.
+
+## Suggested website features
+
+1. Sidebar navigation from this source map.
+2. Markdown rendering + syntax highlighting.
+3. Previous/next navigation.
+4. Version/release-state banner.
+5. Release pages.
+6. Full-text search.
+7. Copy buttons for code blocks.
+8. Mobile navigation.
+9. GitHub source/edit links.
+
+Later:
+
+- generated symbol reference,
+- versioned snapshots,
+- interactive examples/playgrounds,
+- release comparison pages.
 
-## Release workflow
+## Source conventions
 
-Before publishing a BCP release:
+- one H1 per page,
+- stable heading hierarchy,
+- fenced code blocks with language tags,
+- relative links between docs,
+- exact public API names,
+- clear stable/RC/roadmap labels,
+- security limitations next to affected APIs,
+- runnable examples where possible,
+- no private/internal modules presented as public API.
+
+## Release validation
+
+Before publishing:
 
 ```bash
 npm run typecheck
 npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
 npm run rc:check
 ```
 
-The framework repository remains authoritative for API behavior. `bcp-docs` is the presentation layer for this source content.
+For `0.1.26`, package validation must also confirm the staged npm artifact contains:
+
+```text
+@aws-sdk/client-s3
+@aws-sdk/lib-storage
+busboy
+```
+
+and the S3/multipart streaming source files/public exports.
+
+## Documentation QA checklist
+
+- linked Markdown files exist,
+- examples use public exports,
+- version/release states are current,
+- Windows direct CLI examples use `npm exec -- bcp-framework`,
+- upload/storage/auth security caveats are present,
+- route names match the current router,
+- release notes match the framework version,
+- S3 credentials are never shown as public browser variables,
+- roadmap APIs are not presented as published guarantees.
 
-## Next milestone
+## Next direction after 0.1.26
+
+Recommended `0.1.27` direction:
+
+- signed URLs where needed,
+- object listing/copy/move capabilities,
+- broader production hardening,
+- graceful shutdown/resource cleanup,
+- stronger storage/provider diagnostics.
+
+These are roadmap items, not `0.1.26` guarantees.
+
+## Repository authority
+
+The framework repository remains authoritative for:
+
+```text
+source
+public exports
+tests
+docs
+release notes
+```
 
-After 0.1.24, the planned follow-up is `0.1.25` for upload/storage adapters and production file-delivery hardening unless roadmap priorities are regrouped.
+`bcp-docs-web` is the presentation/search/navigation layer for this content.