@chidchanun/bcp 0.1.22 → 0.1.24

package/docs/developer-tools.md

@@ -2,12 +2,64 @@
 
 BCP Framework 0.1.22 adds project diagnostics and runtime inspection commands for debugging a BCP application without starting the development server.
 
+## CLI executable names
+
+The published BCP package exposes two executable names that point to the same CLI:
+
+```text
+bcp
+bcp-framework
+```
+
+`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` directly in PowerShell can launch the SQL Server utility instead of BCP Framework.
+
+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
+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
+```
+
+Or call the generated Windows shim explicitly:
+
+```powershell
+.\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:
@@ -54,12 +106,29 @@ Invalid hook call. Hooks can only be called inside of the body of a function com
 
 For local release testing, install the packed `.tgz` artifact instead of linking `.package/bcp` directly into another project. A packed package lets the BCP peer dependencies resolve from the application's normal `node_modules` tree.
 
+### Duplicate BCP package protection
+
+A BCP application must not load `node_modules/bcp` and `node_modules/@chidchanun/bcp` as two separate framework copies.
+
+The CLI performs a startup preflight. If both package roots exist, runtime commands such as `dev`, `build`, and `start` stop before SSR starts. Two framework copies create separate React contexts, which can make APIs such as `useLoaderData()` incorrectly report missing loader data even when the route loader executed successfully.
+
+For local release verification, install the tarball under the existing `bcp` dependency key instead of adding the scoped package beside it:
+
+```powershell
+npm install `
+  --no-save `
+  --package-lock=false `
+  "bcp@file:D:\bcp-framework\.package\artifacts\chidchanun-bcp-0.1.22.tgz"
+```
+
+The installed folder remains `node_modules/bcp` even when the package inside the tarball is published as `@chidchanun/bcp`.
+
 ## `bcp inspect`
 
 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:
@@ -78,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.
@@ -115,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/development-logging.md

@@ -1,13 +1,241 @@
-# Development request logging
+# Logging and observability
 
-BCP keeps development request output focused on application API traffic.
+BCP Framework 0.1.23 adds a structured server logger and upgrades development request timing output while keeping framework-internal browser/bootstrap traffic quiet by default.
 
-By default, request-style console lines are shown for application API routes such as:
+## Server logger
+
+Import logging APIs from the server-only `bcp/server` entry:
+
+```ts
+import {
+    logger,
+} from "bcp/server";
+
+logger.info(
+    "Application started",
+    {
+        service: "catalog",
+    }
+);
+```
+
+Available levels are:
+
+```text
+debug
+info
+warn
+error
+silent
+```
+
+The default level is `info`.
+
+Structured fields can contain strings, numbers, booleans, objects, arrays, `Error` values and `bigint` values. Circular references are replaced with `[Circular]` rather than crashing the logger.
+
+## Request-scoped logging
+
+Use `requestLogger()` while handling an API route, loader, guard or form action:
+
+```ts
+import {
+    requestLogger,
+} from "bcp/server";
+
+export async function loader() {
+    const log =
+        await requestLogger({
+            feature: "categories",
+        });
+
+    log.info(
+        "Loading categories"
+    );
+
+    return {
+        items: [],
+    };
+}
+```
+
+The returned child logger automatically binds the current request identity:
+
+```text
+requestId
+method
+path
+```
+
+`requestId` uses the same request-scoped value exposed by `requestId()`: a valid incoming `X-Request-Id` is reused, otherwise BCP creates a UUID for the request.
+
+## Response request ID
+
+When an application wants to return the request identity to a caller, wrap a response with `attachRequestId()`:
+
+```ts
+import {
+    attachRequestId,
+    json,
+} from "bcp/server";
+
+export async function GET() {
+    return attachRequestId(
+        json({
+            ok: true,
+        })
+    );
+}
+```
+
+The returned response includes:
 
 ```text
-GET /api/users 200 1.24ms
+X-Request-Id: <current request id>
+```
+
+This helper preserves the original response status, status text, body and headers.
+
+## Child loggers
+
+Bind shared fields once with `child()`:
+
+```ts
+import {
+    logger,
+} from "bcp/server";
+
+const dbLog =
+    logger.child({
+        component: "database",
+    });
+
+dbLog.debug(
+    "Executing query",
+    {
+        operation: "users.list",
+    }
+);
 ```
 
-BCP suppresses framework and browser bootstrap traffic such as `/_bcp/*`, page/document requests, public static assets, and the generated Tailwind stylesheet endpoint `/api/bcp-styles`.
+Child bindings are inherited by further child loggers.
+
+## Log level
+
+Set the minimum log level with:
+
+```bash
+BCP_LOG_LEVEL=debug
+```
+
+Supported values:
+
+```text
+debug
+info
+warn
+error
+silent
+```
+
+Invalid or missing values fall back to `info`.
+
+Use `debug` during framework/application diagnostics to see development SSR and module-import timing events.
+
+## Log format
 
-Build, SSR, Fast Refresh, watcher and error diagnostics are not affected by this filter.
+Human-readable output is the default:
+
+```bash
+BCP_LOG_FORMAT=pretty
+```
+
+Example:
+
+```text
+[2026-08-27T10:00:00.000Z] [INFO] [bcp] User loaded userId=42
+```
+
+For containers, log collectors and CI systems use JSON lines:
+
+```bash
+BCP_LOG_FORMAT=json
+```
+
+Example:
+
+```json
+{"timestamp":"2026-08-27T10:00:00.000Z","level":"info","logger":"bcp","message":"User loaded","userId":42}
+```
+
+Each log call emits exactly one line.
+
+## Development HTTP logging
+
+Development request output remains focused on application API traffic. BCP suppresses request-style logs for framework and browser bootstrap traffic such as:
+
+```text
+/_bcp/*
+/api/bcp-styles
+page/document requests
+public static assets
+```
+
+An application API request is converted into the structured logger format. With pretty output it resembles:
+
+```text
+[2026-08-27T10:00:00.000Z] [INFO] [bcp-dev] HTTP request event=http.request method=GET path=/api/users status=200 durationMs=1.24
+```
+
+With `BCP_LOG_FORMAT=json` the same event is emitted as one JSON object containing:
+
+```text
+event=http.request
+method
+path
+status
+durationMs
+```
+
+Existing development `Import: ...ms` and `SSR: ...ms` measurements are converted into `debug` events:
+
+```text
+module.import
+ssr.render
+```
+
+They are therefore visible when `BCP_LOG_LEVEL=debug` and stay out of normal `info` output.
+
+## Errors
+
+Pass an `Error` as a structured field:
+
+```ts
+try {
+    // ...
+} catch (error) {
+    logger.error(
+        "Operation failed",
+        {
+            error,
+        }
+    );
+}
+```
+
+`Error` values are serialized with their name, message, stack and cause when available.
+
+## Environment example
+
+A development `.env.local` can use:
+
+```text
+BCP_LOG_LEVEL=debug
+BCP_LOG_FORMAT=pretty
+```
+
+A production/container environment can use:
+
+```text
+BCP_LOG_LEVEL=info
+BCP_LOG_FORMAT=json
+```

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.