@chidchanun/bcp 0.1.24 → 0.1.25

package/docs/README.md

@@ -1,61 +1,134 @@
 # 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 so it can be consumed later by the **`bcp-docs-web`** documentation website.
 
-> Documentation target: BCP Framework `0.1.24`
+> **Documentation target:** BCP Framework `0.1.25`
+>
+> 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.
 
-When framework behavior changes, update framework source/tests first, then the matching file under `docs/`, then the release note under `docs/releases/`.
+## Documentation goals
 
-## Recommended website navigation
+The documentation source should make it possible to build `bcp-docs-web` without duplicating framework knowledge into a second repository.
+
+The expected relationship is:
+
+```text
+BCP Framework source/tests
+        ↓
+      docs/
+        ↓
+   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.
+
+## Content 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.
+
+## Recommended `bcp-docs-web` navigation
+
+The website should use these top-level groups:
+
+```text
+Getting Started
+Routing & Data
+Authentication
+Database
+Runtime & Infrastructure
+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/application-modules` | `application-modules.md` | Client/server boundaries |
-| `/docs/deployment` | `deployment.md` | Production deployment |
-| `/docs/updating` | `updating.md` | Framework upgrades |
+| `/docs/configuration` | `configuration.md` | Framework configuration and environment behavior |
+| `/docs/application-modules` | `application-modules.md` | Client/server boundaries and module rules |
+| `/docs/deployment` | `deployment.md` | Standalone production deployment |
+| `/docs/updating` | `updating.md` | Framework upgrade workflow |
 
-### 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/form-actions` | `form-actions.md` | Server mutations and 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 |
+| `/docs/file-upload` | `file-upload.md` | Multipart parsing and upload validation |
+| `/docs/storage` | `storage.md` | Storage adapters and production file delivery |
 
 ### 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 and migration 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/developer-tools` | `developer-tools.md` | `doctor` and `inspect` diagnostics |
 | `/docs/development-logging` | `development-logging.md` | Structured logging and observability |
-| `/docs/caching` | `caching.md` | Cache/revalidation |
-| `/docs/security` | `security.md` | Security defaults and body limits |
+| `/docs/caching` | `caching.md` | Cache and revalidation |
+| `/docs/security` | `security.md` | Security defaults and request body limits |
+
+## API Reference grouping
+
+`bcp-docs-web` can derive an API-reference navigation layer from the authored guides.
+
+Recommended entrypoint groups:
+
+```text
+bcp
+bcp/server
+bcp/auth
+bcp/database
+bcp/validation
+bcp/error
+bcp/cache
+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/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
 
@@ -63,29 +136,46 @@ When framework behavior changes, update framework source/tests first, then the m
 
 - React SSR and hydration
 - file-based page/API routing
-- dynamic/catch-all routes
+- dynamic routes
+- catch-all and optional catch-all routes
+- route groups
 - layouts and metadata
 - SPA navigation
-- loaders, guards and form actions
+- server data loaders
+- route guards
+- form actions
 - client islands / partial hydration
-- Fast Refresh and deterministic development hydration
+- Fast Refresh
+- deterministic development hydration
 
 ### Server
 
 - request-scoped server APIs
+- request IDs
 - cookies and redirects
-- JWT sessions and authentication
+- JWT sessions
+- authentication helpers
 - Middleware System v2
-- typed validation and structured errors
-- structured logging with request identity
-- multipart file uploads and local filesystem persistence
+- typed validation
+- structured errors
+- structured logging
+- multipart file uploads
+- upload validation
+- storage adapter contract
+- local filesystem storage adapter
+- production file delivery
+- validators and byte ranges
 
 ### Database
 
 - `bcp/database`
-- MySQL pool/query helpers
+- lazy MySQL pool
+- prepared execution
+- query helpers
 - transactions
-- migrations/status/rollback
+- migrations
+- migration status
+- rollback
 
 ### Developer Experience
 
@@ -93,69 +183,110 @@ When framework behavior changes, update framework source/tests first, then the m
 - `bcp update`
 - `bcp doctor`
 - `bcp inspect`
+- route inspection
 - `bcp-framework` Windows-safe CLI alias
 - standalone production build
+- unit/integration/E2E/package tests
 - release/package smoke checks
 
-## BCP 0.1.24 documentation priorities
+## BCP 0.1.25 documentation focus
 
-### File Upload
+### Storage adapters
 
-BCP 0.1.24 exposes upload helpers through the server-only `bcp/server` entrypoint:
+BCP `0.1.25` introduces the first application-facing storage abstraction through `bcp/server`:
 
 ```ts
 import {
-    parseMultipartFormData,
-    getUploadedFile,
-    requireUploadedFile,
-    validateUploadedFile,
-    saveUploadedFile,
-    sanitizeUploadFileName,
-    UploadError,
+    createLocalStorage,
+    createStorageResponse,
+    normalizeStorageKey,
+    StorageError,
+    storeUploadedFile,
 } from "bcp/server";
 ```
 
-Documentation must make the following boundaries clear:
+The documentation must make these 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.
+- `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 `file-upload.md`.
+See `storage.md`.
 
-### Dev route/client bundle synchronization
+### File Upload
 
-0.1.24 also fixes a development-only graph drift that could produce:
+BCP `0.1.24` introduced:
 
-```text
-Client bundle was not found for route "/docs/[...slug]".
-```
+- 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`
 
-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.
+### Production auth guard stabilization
 
-### Logging & Observability
+The `0.1.24` stabilization cycle unified standalone guard/action authentication imports with the active request-context runtime.
 
-0.1.23 introduced:
+This prevents production-only failures where APIs such as `cookies()`, `getSession()`, `requireAuth()` or `requireRole()` could see a different request-context instance after bundling.
 
-- `logger` / `createLogger()`
-- request-scoped `requestLogger()`
-- log levels and JSON format
-- `X-Request-Id` helpers
-- structured development request/SSR timing
+### Development route graph synchronization
+
+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.
+
+The development gateway now compares the actual page route graph and refreshes the internal client bundler when pathname/page/layout topology changes.
+
+### Logging and observability
+
+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.
 
 See `development-logging.md`.
 
-### Developer Tools
+### Developer tools
 
-0.1.22 introduced `bcp doctor` and `bcp inspect`, JSON reports, duplicate React diagnostics and duplicate BCP-install protection.
+BCP `0.1.22` introduced:
+
+- `bcp doctor`,
+- `bcp inspect`,
+- JSON diagnostic output,
+- duplicate React detection,
+- duplicate BCP installation protection,
+- Windows-safe `bcp-framework` CLI alias.
 
 See `developer-tools.md`.
 
-## Commands
+## CLI commands
 
 ```bash
 bcp dev
@@ -175,19 +306,29 @@ bcp db status
 bcp db rollback
 ```
 
-On Windows systems where SQL Server owns `bcp.exe`, direct shell commands can use:
+On Windows systems where Microsoft SQL Server owns `bcp.exe`, 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
 ```
 
-## Releases
+Inside npm scripts, `bcp` remains safe because npm prepends `node_modules/.bin` to `PATH`.
+
+## Release documentation
 
-Recommended release routes:
+Release notes live under:
 
 ```text
+docs/releases/
+```
+
+Recommended website release routes:
+
+```text
+/releases/0.1.25
 /releases/0.1.24
 /releases/0.1.23
 /releases/0.1.22
@@ -195,20 +336,133 @@ Recommended release routes:
 /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.
+The website should display a clear release state for each version:
+
+```text
+published
+release candidate
+unreleased development target
+```
+
+Do not infer publication state only from the existence of a Markdown release note.
+
+## Suggested `bcp-docs-web` content model
+
+A future website can represent each Markdown page with metadata similar to:
+
+```ts
+interface DocPage {
+    title: string;
+    slug: string;
+    section: string;
+    sourceFile: string;
+    versionTarget?: string;
+    releaseState?:
+        | "published"
+        | "rc"
+        | "unreleased";
+}
+```
+
+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.
+
+## 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.
+7. Copy buttons for code blocks.
+8. Mobile navigation.
+9. Direct GitHub source/edit links.
+
+Later additions can include:
+
+- generated API symbol reference,
+- versioned documentation snapshots,
+- interactive examples,
+- framework 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.
 
-## Release workflow
+## Release validation
 
-Before publishing a BCP release:
+Before publishing a framework release:
 
 ```bash
 npm run typecheck
 npm run test:unit
+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.
+Release validation should include packed-package smoke verification and representative production application testing.
+
+## Documentation QA checklist
+
+Before a docs release or website sync:
 
-## Next milestone
+- all 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,
+- route names match the current router,
+- release notes match the framework version,
+- no generated `.bcp-framework` paths are presented as user-authored source files.
+
+## Roadmap
+
+After `0.1.25`, the current planned framework direction is:
+
+1. S3-compatible / cloud storage integration.
+2. Production upload streaming.
+3. Broader storage adapter ecosystem.
+4. Additional production hardening.
+
+These are roadmap items, not published API 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` should be treated as the presentation/search/navigation layer for this content rather than a competing documentation source.

package/docs/releases/0.1.25.md

@@ -0,0 +1,132 @@
+# BCP Framework 0.1.25
+
+BCP 0.1.25 adds the first storage-adapter contract and hardened file-delivery responses on top of the multipart/file upload foundation introduced in 0.1.24.
+
+## Highlights
+
+- Added `StorageAdapter` for application-level storage abstraction.
+- Added built-in `createLocalStorage()` filesystem adapter.
+- Added traversal-safe relative storage keys.
+- Added overwrite protection by default.
+- Added persistent local metadata for content type and SHA-256 identity.
+- Added `stat()`, ranged `read()`, `exists()` and `delete()` operations.
+- Added `storeUploadedFile()` to write validated multipart `File` values into any storage adapter.
+- Added `createStorageResponse()` for production GET/HEAD delivery.
+- Added strong ETag validators for objects written through the local adapter.
+- Added `If-None-Match`, `If-Modified-Since` and `If-Range` support.
+- Added single byte-range delivery with `206 Partial Content`.
+- Added `416 Range Not Satisfiable` handling.
+- Added safe `Content-Disposition` generation for downloads.
+- Added conservative private cache defaults.
+- Added storage/file-delivery unit and public-export regression coverage.
+
+## Storage abstraction
+
+```ts
+import {
+    createLocalStorage,
+} from "bcp/server";
+
+const storage =
+    createLocalStorage({
+        directory:
+            "./uploads",
+    });
+
+await storage.put(
+    "documents/report.txt",
+    "Hello",
+    {
+        contentType:
+            "text/plain",
+    }
+);
+```
+
+The public adapter contract includes:
+
+```text
+put
+stat
+read
+exists
+delete
+```
+
+Application code can depend on `StorageAdapter` instead of the local filesystem implementation.
+
+## Upload integration
+
+```ts
+const stored =
+    await storeUploadedFile(
+        file,
+        {
+            storage,
+            key:
+                "avatars/user-101.webp",
+        }
+    );
+```
+
+The upload validation APIs from 0.1.24 remain compatible. `storeUploadedFile()` is additive and reuses the same `UploadConstraints` validation model.
+
+## File delivery
+
+```ts
+return createStorageResponse(
+    request,
+    storage,
+    "documents/report.pdf",
+    {
+        disposition:
+            "attachment",
+        downloadName:
+            "report.pdf",
+    }
+);
+```
+
+The helper supports:
+
+```text
+200 full response
+206 single byte range
+304 validator hit
+404 missing object
+405 unsupported request method
+416 invalid/unsupported range
+```
+
+`HEAD` returns the same entity metadata headers without reading object bytes into the response body.
+
+Multiple ranges are intentionally unsupported in 0.1.25 and return `416`.
+
+## Cache policy
+
+The default is:
+
+```text
+private, max-age=0, must-revalidate
+```
+
+Applications can explicitly opt public immutable files into stronger caching.
+
+## Security model
+
+- Storage keys reject absolute paths and traversal segments.
+- BCP's local metadata directory cannot be addressed as an application storage key.
+- Existing objects are not overwritten unless requested explicitly.
+- Download filenames are stripped of path/control characters before being placed in response headers.
+- Storage keys do not provide authorization; route/API guards must still enforce ownership and access permissions.
+- Content type remains metadata, not content-signature verification.
+
+## Compatibility
+
+`saveUploadedFile()` from 0.1.24 remains supported. Applications can migrate incrementally to `StorageAdapter` / `storeUploadedFile()` when they need backend-independent storage behavior.
+
+The route-graph synchronization and standalone auth-guard fixes completed during the 0.1.24 stabilization cycle remain part of the 0.1.25 baseline.
+
+## Next milestone
+
+The next planned milestone is BCP 0.1.26 — storage adapter ecosystem / S3-compatible integration and production upload streaming, unless roadmap priorities are regrouped.