@chidchanun/bcp 0.1.23 → 0.1.25

package/docs/auth-route-guards.md

@@ -211,6 +211,20 @@ export function guard() {
 }
 ```
 
+## Standalone production behavior
+
+BCP 0.1.24 keeps `bcp/auth` inside the same production guard runtime graph as `runWithRequestContext()`. This guarantees that `requireAuth()`, `requireRole()`, `auth()`, `getSession()` and `cookies()` observe the active request after `bcp build`, rather than resolving through a second framework request-context instance.
+
+This fixes the production-only failure:
+
+```text
+BCP Framework: server request APIs can only be used while handling a request.
+```
+
+No application guard changes are required. Continue importing authentication helpers from `bcp/auth` normally.
+
+The production form-action bundle applies the same runtime unification because route guards may execute before an action.
+
 ## Security boundary
 
 `bcp/auth` is server-only. BCP blocks it from page/client graphs and maps its browser export to the server-only runtime guard. Authentication and authorization checks should stay in guards, loaders, actions, API routes, or other server modules.

package/docs/developer-tools.md

@@ -11,34 +11,55 @@ bcp
 bcp-framework
 ```
 
-`bcp` remains the primary and backward-compatible command.
+`bcp` remains the primary and backward-compatible executable name inside npm scripts.
 
-On Windows, Microsoft SQL Server also installs a native utility named `bcp.exe`. When that executable appears earlier on `PATH`, typing `bcp` in PowerShell can launch the SQL Server utility instead of BCP Framework.
+On Windows, Microsoft SQL Server also installs a native utility named `bcp.exe`. When that executable appears earlier on `PATH`, typing `bcp` directly in PowerShell can launch the SQL Server utility instead of BCP Framework.
 
-Use the Windows-safe alias in that situation:
+PowerShell also does not add an application's `node_modules/.bin` directory to its normal interactive `PATH`. Therefore the recommended interactive Windows invocation is the project-local executable through npm:
 
 ```powershell
-bcp-framework doctor
-bcp-framework inspect
-bcp-framework dev
-bcp-framework build
-bcp-framework update
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
+npm exec -- bcp-framework update
 ```
 
-You can also explicitly run the project-local executable with npm:
+Or call the generated Windows shim explicitly:
 
 ```powershell
-npm exec -- bcp doctor
+.\node_modules\.bin\bcp-framework.cmd doctor
 ```
 
 BCP application npm scripts can continue using `bcp dev`, `bcp build`, and other existing commands because npm places the project's `node_modules/.bin` directory on the script `PATH` before system executables.
 
+### Framework source checkout
+
+The framework source repository itself is a private development workspace and is not an installed copy of the published package. Merely opening PowerShell in `D:\bcp-framework` does not make `bcp-framework` available on `PATH`.
+
+`bcp doctor` and `bcp inspect` are application diagnostics: they expect an application root with `app/` plus an installed BCP dependency. Do not use them as the release-health command for the framework source checkout.
+
+For framework development and release validation, use:
+
+```powershell
+npm run typecheck
+npm run test:unit
+npm run rc:check
+```
+
+After a packed or published package is installed into an application such as `bcp-docs`, run:
+
+```powershell
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+```
+
 ## `bcp doctor`
 
-Run a health check from the application root:
+Run a health check from an installed application root. On Windows PowerShell, prefer:
 
-```bash
-bcp doctor
+```powershell
+npm exec -- bcp-framework doctor
 ```
 
 The command checks:
@@ -106,8 +127,8 @@ The installed folder remains `node_modules/bcp` even when the package inside the
 
 Use `inspect` when you want a deterministic snapshot of the project inputs BCP sees:
 
-```bash
-bcp inspect
+```powershell
+npm exec -- bcp-framework inspect
 ```
 
 It prints:
@@ -126,16 +147,16 @@ It prints:
 
 Both commands support machine-readable output:
 
-```bash
-bcp doctor --json
-bcp inspect --json
+```powershell
+npm exec -- bcp-framework doctor --json
+npm exec -- bcp-framework inspect --json
 ```
 
-You can also target another project directory:
+You can also target another installed BCP application directory:
 
-```bash
-bcp doctor --root ../my-app --json
-bcp inspect --root ../my-app --json
+```powershell
+npm exec -- bcp-framework doctor --root ..\my-app --json
+npm exec -- bcp-framework inspect --root ..\my-app --json
 ```
 
 `--json` is intentionally limited to `doctor` and `inspect` so other CLI commands keep their existing human-oriented output contracts.
@@ -163,4 +184,6 @@ A simple project-health gate can use:
 bcp doctor --json > bcp-doctor.json
 ```
 
+Inside npm scripts or CI package-script execution, npm already places `node_modules/.bin` on `PATH`.
+
 The command exits non-zero when blocking checks fail, while the JSON report remains available for CI logs or artifacts.

package/docs/file-upload.md

@@ -0,0 +1,280 @@
+# File Upload
+
+BCP Framework 0.1.24 adds server-only multipart and file-storage helpers through `bcp/server`.
+
+## Basic API route
+
+```ts
+import {
+    parseMultipartFormData,
+    requireUploadedFile,
+    saveUploadedFile,
+} from "bcp/server";
+
+export async function POST(
+    request: Request
+) {
+    const formData =
+        await parseMultipartFormData(
+            request,
+            {
+                maxBytes:
+                    8 * 1024 * 1024,
+            }
+        );
+
+    const file =
+        requireUploadedFile(
+            formData,
+            "file",
+            {
+                maxBytes:
+                    5 * 1024 * 1024,
+                allowedTypes: [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                ],
+                allowedExtensions: [
+                    ".png",
+                    ".jpg",
+                    ".jpeg",
+                    ".webp",
+                ],
+            }
+        );
+
+    const saved =
+        await saveUploadedFile(
+            file,
+            {
+                directory:
+                    "./uploads",
+            }
+        );
+
+    return Response.json({
+        fileName:
+            saved.fileName,
+        size:
+            saved.size,
+        checksumSha256:
+            saved.checksumSha256,
+    });
+}
+```
+
+## Request body limit
+
+BCP's security gateway enforces the framework-wide request body limit before the request reaches the application server.
+
+The default is 1 MiB. Applications that accept larger uploads must explicitly raise it:
+
+```ts
+// bcp.config.ts
+import {
+    defineConfig,
+} from "bcp/config";
+
+export default defineConfig({
+    server: {
+        bodyLimit:
+            10 * 1024 * 1024,
+    },
+});
+```
+
+The same setting can be supplied with `BCP_BODY_LIMIT`.
+
+Keep `server.bodyLimit` greater than or equal to the multipart limit used by `parseMultipartFormData()`.
+
+## Multipart parsing
+
+```ts
+const formData =
+    await parseMultipartFormData(
+        request,
+        {
+            maxBytes:
+                10 * 1024 * 1024,
+        }
+    );
+```
+
+The helper:
+
+- requires `multipart/form-data`,
+- rejects a declared `Content-Length` above `maxBytes`,
+- validates the parsed form payload size,
+- throws `UploadError` with HTTP-oriented status information on validation failures.
+
+`maxBytes` is optional. The framework-wide `server.bodyLimit` remains the outer request limit.
+
+## Reading files
+
+Use `getUploadedFile()` for optional files:
+
+```ts
+const avatar =
+    getUploadedFile(
+        formData,
+        "avatar"
+    );
+
+if (!avatar) {
+    // no file supplied
+}
+```
+
+Use `requireUploadedFile()` when a file is mandatory:
+
+```ts
+const avatar =
+    requireUploadedFile(
+        formData,
+        "avatar"
+    );
+```
+
+A missing required file throws `UploadError` with code `FILE_REQUIRED` and status `400`.
+
+## File constraints
+
+`getUploadedFile()`, `requireUploadedFile()` and `saveUploadedFile()` can validate:
+
+```ts
+{
+    maxBytes: 5 * 1024 * 1024,
+    allowedTypes: [
+        "application/pdf",
+    ],
+    allowedExtensions: [
+        ".pdf",
+    ],
+}
+```
+
+Supported checks are:
+
+- maximum file size,
+- MIME type allowlist,
+- extension allowlist.
+
+MIME type and file extension are metadata supplied with the upload. They are useful validation signals but are not content-signature verification. Applications accepting security-sensitive formats should inspect the file content or magic bytes before trusting the file type.
+
+## Saving files
+
+```ts
+const saved =
+    await saveUploadedFile(
+        file,
+        {
+            directory:
+                "./uploads/documents",
+        }
+    );
+```
+
+When `fileName` is omitted, BCP generates a UUID-based storage name while preserving a short sanitized extension.
+
+The result contains:
+
+```ts
+{
+    originalName: string;
+    fileName: string;
+    path: string;
+    type: string;
+    size: number;
+    checksumSha256: string;
+}
+```
+
+Files are created with exclusive-write behavior by default. An existing destination produces `FILE_EXISTS` instead of silently overwriting data.
+
+Use `overwrite: true` only when replacement is intentional:
+
+```ts
+await saveUploadedFile(
+    file,
+    {
+        directory:
+            "./uploads",
+        fileName:
+            "avatar.webp",
+        overwrite:
+            true,
+    }
+);
+```
+
+## File-name safety
+
+`saveUploadedFile()` sanitizes the final file name and verifies that the resolved destination remains inside the configured directory.
+
+You can use the same sanitizer independently:
+
+```ts
+import {
+    sanitizeUploadFileName,
+} from "bcp/server";
+
+const safeName =
+    sanitizeUploadFileName(
+        userFileName
+    );
+```
+
+Path separators, control characters and operating-system-invalid filename characters are removed or replaced.
+
+## Upload errors
+
+```ts
+import {
+    UploadError,
+} from "bcp/server";
+
+try {
+    // upload work
+} catch (error) {
+    if (
+        error instanceof UploadError
+    ) {
+        return Response.json(
+            {
+                error: {
+                    code:
+                        error.code,
+                    message:
+                        error.message,
+                },
+            },
+            {
+                status:
+                    error.status,
+            }
+        );
+    }
+
+    throw error;
+}
+```
+
+Current error codes include:
+
+```text
+INVALID_MULTIPART
+UPLOAD_TOO_LARGE
+FILE_REQUIRED
+FILE_TOO_LARGE
+FILE_TYPE_NOT_ALLOWED
+FILE_EXTENSION_NOT_ALLOWED
+INVALID_FILE_NAME
+FILE_EXISTS
+```
+
+## Storage model
+
+The 0.1.24 foundation writes to the local filesystem. It does not provide S3/object-storage adapters, multipart streaming directly to object storage, virus scanning or image transcoding yet.
+
+For horizontally scaled applications, use shared/object storage rather than relying on instance-local disk.

package/docs/releases/0.1.24.md

@@ -0,0 +1,166 @@
+# BCP Framework 0.1.24
+
+BCP 0.1.24 introduces the File Upload foundation and includes production/development stabilization fixes found while validating the framework against `bcp-docs`.
+
+## Highlights
+
+- Added multipart upload parsing through `bcp/server`.
+- Added optional and required uploaded-file helpers.
+- Added maximum multipart and per-file size validation.
+- Added MIME type and extension allowlists.
+- Added safe local file persistence with UUID storage names by default.
+- Added filename sanitization and destination traversal protection.
+- Existing files are not overwritten unless `overwrite: true` is explicitly requested.
+- Saved upload metadata includes SHA-256 checksum, original name, stored name, MIME type and byte size.
+- Added `UploadError` with HTTP-oriented status codes and stable upload error codes.
+- Added unit and package-export regression coverage.
+- Fixed development route graph synchronization so page/client bundles rebuild when the actual route topology changes even if the filesystem watcher reports the change as `change` rather than `add`/`unlink`.
+- Fixed standalone auth guards using `requireAuth()` / `requireRole()` after `bcp build` by keeping `bcp/auth` inside the same bundled request-context runtime as the guard evaluator.
+- Applied the same auth-runtime unification to production form-action bundles so guarded actions do not split request context.
+- Added standalone E2E coverage that builds the application and executes a real `requireRole("admin")` guard with a signed session cookie.
+
+## Development client-bundle graph fix
+
+A development server could previously reach this inconsistent state:
+
+```text
+routes contains /docs/[...slug]
+clientBundles does not contain /docs/[...slug]
+```
+
+The resulting request failed with:
+
+```text
+BCP Framework Error:
+Error: Client bundle was not found for route "/docs/[...slug]".
+```
+
+Restarting after deleting `.bcp-framework` rebuilt the graph and hid the problem.
+
+BCP 0.1.24 tracks the actual page route graph separately at the dev gateway. When pathname, page file or layout topology changes, the internal development server/client bundler is refreshed automatically on the same upstream port. The behavior no longer depends on whether Windows/editor filesystem events are classified as `add`, `unlink` or `change`.
+
+## Production auth-guard request context fix
+
+A standalone build could previously fail when an application guard imported authentication helpers from `bcp/auth`:
+
+```ts
+import {
+    requireRole,
+} from "bcp/auth";
+
+export async function guard() {
+    return requireRole(
+        "admin"
+    );
+}
+```
+
+The production guard evaluator bundled its own `runWithRequestContext()` runtime, but `bcp/auth` could remain an external package import. This created two request-context module instances inside one request path:
+
+```text
+guards.mjs request context
+        ↓
+application guard
+        ↓
+external bcp/auth
+        ↓
+second request context
+```
+
+The authentication helper then failed while reading cookies with:
+
+```text
+BCP Framework: server request APIs can only be used while handling a request.
+```
+
+BCP 0.1.24 resolves `bcp/auth` into the guard build graph so `requireAuth()`, `requireRole()`, sessions and cookies share the same active request context as the production guard evaluator. The production action bundle uses the same rule because route guards may execute before server mutations.
+
+## Upload example
+
+```ts
+import {
+    parseMultipartFormData,
+    requireUploadedFile,
+    saveUploadedFile,
+} from "bcp/server";
+
+export async function POST(
+    request: Request
+) {
+    const formData =
+        await parseMultipartFormData(
+            request,
+            {
+                maxBytes:
+                    8 * 1024 * 1024,
+            }
+        );
+
+    const file =
+        requireUploadedFile(
+            formData,
+            "file",
+            {
+                maxBytes:
+                    5 * 1024 * 1024,
+                allowedTypes: [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                ],
+                allowedExtensions: [
+                    ".png",
+                    ".jpg",
+                    ".jpeg",
+                    ".webp",
+                ],
+            }
+        );
+
+    const saved =
+        await saveUploadedFile(
+            file,
+            {
+                directory:
+                    "./uploads",
+            }
+        );
+
+    return Response.json(
+        saved
+    );
+}
+```
+
+## Body-limit relationship
+
+The existing BCP security gateway still enforces `server.bodyLimit` / `BCP_BODY_LIMIT` before request bodies reach application handlers.
+
+The default framework body limit is 1 MiB. Applications accepting larger files must raise the framework body limit as well as choosing appropriate multipart/file limits.
+
+```ts
+export default defineConfig({
+    server: {
+        bodyLimit:
+            10 * 1024 * 1024,
+    },
+});
+```
+
+## Security model
+
+The upload helpers protect storage paths and enforce declared size/type/extension policies, but MIME type and extension do not prove file content. Security-sensitive applications should additionally inspect file signatures/content and run malware scanning when appropriate.
+
+The 0.1.24 storage helper targets local filesystem storage. Object-storage adapters and direct streaming are outside this foundation milestone.
+
+## Compatibility
+
+The upload APIs are additive and server-only. Existing routing, loaders, guards, actions, middleware, authentication, database, validation and logging APIs remain compatible.
+
+The dev route-graph fix changes only rebuild behavior when the discovered page topology has actually changed.
+
+The production auth-guard change affects bundling only: existing `bcp/auth` application imports and guard APIs remain unchanged.
+
+## Next milestone
+
+The next planned milestone is BCP 0.1.25 — upload/storage adapters and production file-delivery hardening, unless roadmap priorities are regrouped.

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.