@chidchanun/bcp 0.1.23 → 0.1.24

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",

package/packages/bundler/src/server-production-actions.ts

@@ -131,6 +131,11 @@ export async function buildProductionActions(
             frameworkDirectory,
             "../../client/src/server.ts"
         );
+    const frameworkAuthEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/auth.ts"
+        );
     const frameworkServerOnlyEntry =
         path.resolve(
             frameworkDirectory,
@@ -187,6 +192,16 @@ export async function buildProductionActions(
                                     frameworkServerEntry,
                             })
                         );
+                        buildApi.onResolve(
+                            {
+                                filter:
+                                    /^bcp\/auth$/,
+                            },
+                            () => ({
+                                path:
+                                    frameworkAuthEntry,
+                            })
+                        );
                         buildApi.onResolve(
                             {
                                 filter:

package/packages/bundler/src/server-production-guards.ts

@@ -118,6 +118,11 @@ export async function buildProductionGuards(
             frameworkDirectory,
             "../../client/src/server.ts"
         );
+    const frameworkAuthEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/auth.ts"
+        );
     const frameworkServerOnlyEntry =
         path.resolve(
             frameworkDirectory,
@@ -174,6 +179,16 @@ export async function buildProductionGuards(
                                     frameworkServerEntry,
                             })
                         );
+                        buildApi.onResolve(
+                            {
+                                filter:
+                                    /^bcp\/auth$/,
+                            },
+                            () => ({
+                                path:
+                                    frameworkAuthEntry,
+                            })
+                        );
                         buildApi.onResolve(
                             {
                                 filter:

package/packages/client/src/server.ts

@@ -30,6 +30,22 @@ export {
     type LoggerOptions,
 } from "../../server/src/logger.js";
 
+export {
+    getUploadedFile,
+    parseMultipartFormData,
+    requireUploadedFile,
+    sanitizeUploadFileName,
+    saveUploadedFile,
+    UploadError,
+    validateUploadedFile,
+
+    type MultipartUploadOptions,
+    type SaveUploadedFileOptions,
+    type SavedUploadedFile,
+    type UploadConstraints,
+    type UploadErrorCode,
+} from "../../server/src/upload.js";
+
 export {
     json,
     redirect,