@chidchanun/bcp 0.1.25 → 0.1.27

package/docs/README.md

@@ -1,16 +1,12 @@
 # BCP Framework Documentation Source
 
-The `docs/` directory is the documentation source of truth for BCP Framework and is intentionally organized so it can be consumed later by the **`bcp-docs-web`** documentation website.
+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.25`
+> **Documentation target:** BCP Framework `0.1.27`
 >
-> The documentation target can be newer than the version currently published to npm. Unreleased behavior must be labeled as a development target until release validation and publication are complete.
+> **Release state:** unreleased development target. Do not label `0.1.27` as published until RC validation and npm publication complete.
 
-## Documentation goals
-
-The documentation source should make it possible to build `bcp-docs-web` without duplicating framework knowledge into a second repository.
-
-The expected relationship is:
+## Documentation flow
 
 ```text
 BCP Framework source/tests
@@ -20,28 +16,27 @@ BCP Framework source/tests
    bcp-docs-web
 ```
 
-Framework source and tests remain authoritative for behavior. Markdown under `docs/` is the authored documentation layer. The future website should primarily render, organize and search this source instead of becoming a separate source of truth.
+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.
 
-## Content update rule
+## Update rule
 
 When framework behavior changes:
 
 1. Update framework source.
-2. Add or update regression tests.
-3. Update the matching documentation file under `docs/`.
-4. Update the release note under `docs/releases/` when the change belongs to a release milestone.
-5. Only present the feature as published after release validation and npm publication complete.
+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
 
-The website should use these top-level groups:
-
 ```text
 Getting Started
 Routing & Data
 Authentication
 Database
 Runtime & Infrastructure
+Storage & Uploads
 API Reference
 Releases
 ```
@@ -51,10 +46,10 @@ Releases
 | Website route | Markdown source | Purpose |
 | --- | --- | --- |
 | `/docs/getting-started` | `getting-started.md` | Create and run a BCP application |
-| `/docs/configuration` | `configuration.md` | Framework configuration and environment behavior |
-| `/docs/application-modules` | `application-modules.md` | Client/server boundaries and module rules |
+| `/docs/configuration` | `configuration.md` | Framework configuration/environment |
+| `/docs/application-modules` | `application-modules.md` | Client/server boundaries |
 | `/docs/deployment` | `deployment.md` | Standalone production deployment |
-| `/docs/updating` | `updating.md` | Framework upgrade workflow |
+| `/docs/updating` | `updating.md` | Framework upgrades |
 
 ### Routing & Data
 
@@ -63,12 +58,10 @@ Releases
 | `/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 and forms |
+| `/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 and upload validation |
-| `/docs/storage` | `storage.md` | Storage adapters and production file delivery |
 
 ### Authentication
 
@@ -83,7 +76,7 @@ Releases
 | Website route | Markdown source | Purpose |
 | --- | --- | --- |
 | `/docs/database` | `database.md` | MySQL database primitives |
-| `/docs/database-migrations` | `database-migrations.md` | Migration CLI and migration files |
+| `/docs/database-migrations` | `database-migrations.md` | Migration CLI/files |
 
 ### Runtime & Infrastructure
 
@@ -91,14 +84,21 @@ Releases
 | --- | --- | --- |
 | `/docs/middleware` | `middleware.md` | Middleware System v2 |
 | `/docs/hydration` | `hydration.md` | SSR/client hydration parity |
-| `/docs/developer-tools` | `developer-tools.md` | `doctor` and `inspect` diagnostics |
-| `/docs/development-logging` | `development-logging.md` | Structured logging and observability |
-| `/docs/caching` | `caching.md` | Cache and revalidation |
-| `/docs/security` | `security.md` | Security defaults and request body limits |
+| `/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/body limits |
 
-## API Reference grouping
+### 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/storage-ecosystem` | `storage-ecosystem.md` | Listing, copy/move, metadata, bulk delete, signed URLs |
+| `/docs/s3-storage` | `s3-storage.md` | S3/R2/MinIO adapter and direct object access |
 
-`bcp-docs-web` can derive an API-reference navigation layer from the authored guides.
+## API Reference ownership
 
 Recommended entrypoint groups:
 
@@ -114,14 +114,10 @@ bcp/config
 bcp/middleware
 ```
 
-The first version of the website does not need generated TypeDoc-style reference pages. It can begin by linking APIs to the guide that owns them, then add generated symbol-level reference later if useful.
-
-Suggested ownership:
-
 | Entrypoint | Primary guide |
 | --- | --- |
 | `bcp` | `routing.md`, `server-data-loaders.md`, `form-actions.md` |
-| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `development-logging.md` |
+| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.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` |
@@ -134,48 +130,47 @@ Suggested ownership:
 
 ### Application
 
-- React SSR and hydration
+- React SSR/hydration
 - file-based page/API routing
-- dynamic routes
-- catch-all and optional catch-all routes
-- route groups
-- layouts and metadata
+- static/dynamic/catch-all/optional-catch-all routes
+- route groups/layouts/metadata
 - SPA navigation
-- server data loaders
-- route guards
-- form actions
+- loaders/guards/form actions
 - client islands / partial hydration
 - Fast Refresh
-- deterministic development hydration
 
 ### Server
 
-- request-scoped server APIs
-- request IDs
-- cookies and redirects
-- JWT sessions
-- authentication helpers
+- request-scoped APIs/cookies/redirects/request IDs
+- JWT sessions/authentication
 - Middleware System v2
-- typed validation
-- structured errors
+- validation/structured errors
 - structured logging
-- multipart file uploads
-- upload validation
-- storage adapter contract
-- local filesystem storage adapter
-- production file delivery
-- validators and byte ranges
+- response caching/security gateway
+
+### Storage & Uploads
+
+- buffered multipart `FormData` upload APIs
+- production streaming multipart upload (`storeMultipartFile()`)
+- backward-compatible `StorageAdapter` contract
+- local filesystem storage
+- S3/R2/MinIO-compatible storage
+- streaming reads/writes and byte ranges
+- ETag/Last-Modified file delivery
+- upload/storage limits and abort cleanup
+- object listing with cursors
+- native/fallback copy and move
+- portable user metadata
+- bulk deletion
+- S3 presigned read/write URLs
 
 ### Database
 
 - `bcp/database`
 - lazy MySQL pool
-- prepared execution
-- query helpers
+- prepared execution/query helpers
 - transactions
-- migrations
-- migration status
-- rollback
+- migrations/status/rollback
 
 ### Developer Experience
 
@@ -183,108 +178,70 @@ Suggested ownership:
 - `bcp update`
 - `bcp doctor`
 - `bcp inspect`
-- route inspection
-- `bcp-framework` Windows-safe CLI alias
+- Windows-safe `bcp-framework` alias
 - standalone production build
-- unit/integration/E2E/package tests
-- release/package smoke checks
+- unit/integration/E2E/package/RC checks
 
-## BCP 0.1.25 documentation focus
+## BCP 0.1.27 documentation focus
 
-### Storage adapters
+### Storage ecosystem
 
-BCP `0.1.25` introduces the first application-facing storage abstraction through `bcp/server`:
+New generic helpers include:
 
 ```ts
 import {
-    createLocalStorage,
-    createStorageResponse,
-    normalizeStorageKey,
-    StorageError,
-    storeUploadedFile,
+    copyStorageObject,
+    createStorageSignedReadUrl,
+    createStorageSignedWriteUrl,
+    deleteStorageObjects,
+    getStorageEcosystemCapabilities,
+    getStorageMetadata,
+    listStorageObjects,
+    moveStorageObject,
+    setStorageMetadata,
 } from "bcp/server";
 ```
 
-The documentation must make these boundaries clear:
-
-- `StorageAdapter` is the application-facing contract.
-- `createLocalStorage()` is the built-in adapter in this milestone.
-- storage keys are logical relative paths, not operating-system paths.
-- absolute paths and traversal segments are rejected.
-- overwrite is opt-in.
-- local metadata persists content type and SHA-256 identity.
-- `createStorageResponse()` supports `GET` and `HEAD`.
-- validators include ETag and Last-Modified behavior.
-- single byte ranges are supported.
-- multiple ranges are intentionally unsupported in `0.1.25` and return `416`.
-- the default cache policy is private/revalidate.
-- public caching must be explicit.
-- storage keys do not replace authentication or authorization.
-
-See `storage.md`.
-
-### File Upload
-
-BCP `0.1.24` introduced:
-
-- multipart parsing,
-- request/file size limits,
-- MIME allowlists,
-- extension allowlists,
-- required/optional file fields,
-- safe local file names,
-- traversal protection,
-- overwrite protection,
-- SHA-256 metadata.
-
-Those APIs remain supported in `0.1.25`.
-
-`storeUploadedFile()` is the bridge between a validated multipart `File` and a `StorageAdapter`.
-
-See:
-
-- `file-upload.md`
-- `storage.md`
-
-### Production auth guard stabilization
-
-The `0.1.24` stabilization cycle unified standalone guard/action authentication imports with the active request-context runtime.
-
-This prevents production-only failures where APIs such as `cookies()`, `getSession()`, `requireAuth()` or `requireRole()` could see a different request-context instance after bundling.
+Document these boundaries clearly:
 
-### Development route graph synchronization
+- ecosystem methods are additive and do not invalidate older `StorageAdapter` implementations,
+- listing cursors are opaque,
+- overwrite remains opt-in,
+- move is copy + delete rather than an atomic distributed transaction,
+- application metadata is portable string metadata and not authorization/business state,
+- `bcp_sha256` is reserved for framework checksum metadata,
+- local storage does not emulate signed URLs,
+- S3 direct-transfer URLs are temporary credentials and require application authorization before issuance.
 
-The `0.1.24` stabilization cycle also fixed a development graph drift where the route scanner could see a new route while the incremental client bundle graph still represented the previous topology.
+See `storage-ecosystem.md`.
 
-The development gateway now compares the actual page route graph and refreshes the internal client bundler when pathname/page/layout topology changes.
+### S3 ecosystem
 
-### Logging and observability
+`createS3Storage()` keeps the same public constructor and now adds:
 
-BCP `0.1.23` introduced:
-
-- `logger`,
-- `createLogger()`,
-- request-scoped `requestLogger()`,
-- log levels,
-- pretty/JSON formats,
-- request IDs,
-- structured development request logging,
-- SSR/import debug timing.
+```text
+ListObjectsV2
+CopyObject
+DeleteObjects
+presigned GetObject
+presigned PutObject
+application metadata
+```
 
-See `development-logging.md`.
+See `s3-storage.md`.
 
-### Developer tools
+### 0.1.26 foundations remain supported
 
-BCP `0.1.22` introduced:
+The following remain part of the storage stack:
 
-- `bcp doctor`,
-- `bcp inspect`,
-- JSON diagnostic output,
-- duplicate React detection,
-- duplicate BCP installation protection,
-- Windows-safe `bcp-framework` CLI alias.
+```text
+putStorageStream()
+readStorageStream()
+storeMultipartFile()
+createStorageResponse()
+```
 
-See `developer-tools.md`.
+`0.1.27` builds on these rather than replacing them.
 
 ## CLI commands
 
@@ -306,7 +263,7 @@ bcp db status
 bcp db rollback
 ```
 
-On Windows systems where Microsoft SQL Server owns `bcp.exe`, direct project-local commands should prefer:
+On Windows, direct project-local commands should prefer:
 
 ```powershell
 npm exec -- bcp-framework doctor
@@ -315,9 +272,9 @@ npm exec -- bcp-framework dev
 npm exec -- bcp-framework build
 ```
 
-Inside npm scripts, `bcp` remains safe because npm prepends `node_modules/.bin` to `PATH`.
+Inside npm scripts, `bcp` is safe because npm prepends `node_modules/.bin` to `PATH`.
 
-## Release documentation
+## Releases
 
 Release notes live under:
 
@@ -325,18 +282,18 @@ Release notes live under:
 docs/releases/
 ```
 
-Recommended website release routes:
+Recommended routes:
 
 ```text
+/releases/0.1.27
+/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
 ```
 
-The website should display a clear release state for each version:
+Use one of these release states:
 
 ```text
 published
@@ -344,11 +301,9 @@ release candidate
 unreleased development target
 ```
 
-Do not infer publication state only from the existence of a Markdown release note.
+The existence of a release note alone does not mean the npm version is published.
 
-## Suggested `bcp-docs-web` content model
-
-A future website can represent each Markdown page with metadata similar to:
+## Suggested website model
 
 ```ts
 interface DocPage {
@@ -364,94 +319,89 @@ interface DocPage {
 }
 ```
 
-The metadata does not need to live in frontmatter immediately. The first implementation can use a route manifest in the docs website and consume Markdown files directly.
+The first `bcp-docs-web` implementation can keep this mapping in a route manifest and consume Markdown directly.
 
 ## Suggested website features
 
-The first useful version of `bcp-docs-web` should prioritize:
-
-1. Sidebar navigation generated from the route/source map.
-2. Markdown rendering with syntax highlighting.
-3. Previous/next page navigation.
-4. Version/development-target banner.
-5. Release note pages.
-6. Search across Markdown content.
+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. Direct GitHub source/edit links.
+9. GitHub source/edit links.
 
-Later additions can include:
+Later:
 
-- generated API symbol reference,
-- versioned documentation snapshots,
-- interactive examples,
-- framework playgrounds,
+- generated symbol reference,
+- versioned snapshots,
+- interactive examples/playgrounds,
 - release comparison pages.
 
 ## Source conventions
 
-For documentation intended for the website:
-
-- use one H1 per source page,
-- keep heading hierarchy stable,
-- use fenced code blocks with language tags,
-- use relative repository links for other docs,
-- keep API names exactly aligned with public exports,
-- distinguish current behavior from roadmap plans,
-- include security limitations next to the API they affect,
-- prefer runnable examples over pseudo APIs,
-- avoid documenting private/internal modules as public APIs.
-
-## Stable vs development documentation
-
-`main` can contain documentation for the next release before npm publication.
-
-Therefore the website must distinguish:
-
-```text
-Documentation target != necessarily current npm stable version
-```
-
-For example, while `0.1.25` is under release validation, `docs/storage.md` can describe the `0.1.25` development target, but the website should not label it as published until the release is actually available.
+- 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 a framework release:
+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
 ```
 
-Release validation should include packed-package smoke verification and representative production application testing.
+For `0.1.27`, package validation must also confirm the staged artifact includes:
 
-## Documentation QA checklist
+```text
+@aws-sdk/client-s3
+@aws-sdk/lib-storage
+@aws-sdk/s3-request-presigner
+busboy
+```
 
-Before a docs release or website sync:
+and the ecosystem runtime/public exports.
+
+## Documentation QA checklist
 
-- all linked Markdown files exist,
+- linked Markdown files exist,
 - examples use public exports,
-- version numbers are current,
-- unreleased features are labeled correctly,
-- Windows CLI instructions use the safe alias where needed,
-- security caveats are present for uploads/storage/authentication,
+- 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,
-- no generated `.bcp-framework` paths are presented as user-authored source files.
+- S3 credentials are never shown as public browser variables,
+- signed URLs are documented as temporary credentials,
+- roadmap APIs are not presented as published guarantees.
 
-## Roadmap
+## Next direction after 0.1.27
 
-After `0.1.25`, the current planned framework direction is:
+Planned `0.1.28 — Production Hardening` focus:
 
-1. S3-compatible / cloud storage integration.
-2. Production upload streaming.
-3. Broader storage adapter ecosystem.
-4. Additional production hardening.
+- graceful HTTP shutdown and active-request draining,
+- database/S3 resource cleanup,
+- trusted proxy and forwarded-header handling,
+- timeout controls,
+- security hardening,
+- Docker/standalone runtime regression coverage,
+- startup/runtime dependency diagnostics.
 
-These are roadmap items, not published API guarantees.
+These remain roadmap items until their source/tests land.
 
 ## Repository authority
 
@@ -465,4 +415,4 @@ docs
 release notes
 ```
 
-`bcp-docs-web` should be treated as the presentation/search/navigation layer for this content rather than a competing documentation source.
+`bcp-docs-web` is the presentation/search/navigation layer for this content.