@chidchanun/bcp 0.1.22 → 0.1.24

package/docs/releases/0.1.22.md

@@ -12,6 +12,35 @@ BCP 0.1.22 adds the first dedicated Developer Tools milestone.
 - Added route conflict and client-boundary validation without starting the dev server.
 - Added development environment diagnostics without printing private environment values.
 - Added unit coverage for CLI parsing, version checks, missing-project diagnostics and deterministic inspection output.
+- Added the `bcp-framework` executable alias for Windows systems where the `bcp` command is already occupied by Microsoft SQL Server's `bcp.exe` utility.
+- Fixed `<Form>` SSR so framework runtime rendering no longer depends on a global `React` binding when an application uses the classic JSX transform.
+- Added CLI preflight protection against installing `bcp` and `@chidchanun/bcp` as two separate framework copies, which can split loader/context state across package instances.
+
+## CLI executable compatibility
+
+The published package now exposes both executable names:
+
+```text
+bcp
+bcp-framework
+```
+
+Both names execute the same BCP Framework CLI. Existing applications and npm scripts can continue using `bcp` unchanged.
+
+On Windows installations that include Microsoft SQL Server tools, use the collision-free alias for direct shell commands:
+
+```powershell
+bcp-framework doctor
+bcp-framework inspect
+bcp-framework dev
+bcp-framework build
+```
+
+Alternatively, explicitly run the project-local `bcp` executable through npm:
+
+```powershell
+npm exec -- bcp doctor
+```
 
 ## `bcp doctor`
 
@@ -66,11 +95,47 @@ If an application is linked directly to a framework staging directory, the appli
 
 For local release verification, continue using packed `.tgz` artifacts rather than installing `.package/bcp` as a linked directory.
 
+## Duplicate BCP package protection
+
+Local tarball verification must keep one BCP package root in the application.
+
+Installing a tarball directly when the application already declares an npm alias named `bcp` can leave both of these paths installed:
+
+```text
+node_modules/bcp
+node_modules/@chidchanun/bcp
+```
+
+That layout is unsafe because application imports can use one `BcpLoaderDataProvider` context while the CLI/SSR runtime uses the other package copy. The visible error can therefore incorrectly say that `useLoaderData()` has no loader data.
+
+BCP 0.1.22 now checks this before runtime commands start and fails with an actionable duplicate-install message.
+
+For local tarball verification, install the artifact under the existing dependency key:
+
+```powershell
+npm install `
+  --no-save `
+  --package-lock=false `
+  "bcp@file:D:\bcp-framework\.package\artifacts\chidchanun-bcp-0.1.22.tgz"
+```
+
+## SSR JSX-runtime compatibility
+
+Framework runtime components must not inherit JSX runtime assumptions from the consuming application's `tsconfig.json`.
+
+`<Form>` now renders its provider and native `<form>` element through `createElement()`. This keeps SSR compatible with both automatic JSX runtime projects and projects that still use the classic JSX transform, where unbound generated `React.createElement(...)` calls would otherwise produce:
+
+```text
+ReferenceError: React is not defined
+```
+
+Regression coverage includes server rendering and a classic-JSX transform check that rejects implicit `React.createElement` output from the Form runtime source.
+
 ## Compatibility
 
 0.1.22 does not change public rendering, routing, database, authentication, validation, middleware or error-handling APIs.
 
-The new functionality is additive CLI tooling. Existing BCP applications can continue using the current commands unchanged.
+The Developer Tools commands and `bcp-framework` executable alias are additive. Existing BCP applications can continue using current commands unchanged.
 
 ## Next milestone
 

package/docs/releases/0.1.23.md

@@ -0,0 +1,131 @@
+# BCP Framework 0.1.23
+
+BCP 0.1.23 introduces the Logging & Observability foundation and carries forward the stabilization fixes verified against the BCP documentation application during the 0.1.22 release-candidate cycle.
+
+## Highlights
+
+- Added structured server logging through `bcp/server`.
+- Added `logger.debug()`, `logger.info()`, `logger.warn()` and `logger.error()`.
+- Added child loggers with persistent structured bindings.
+- Added `requestLogger()` for request-scoped `requestId`, HTTP method and path bindings.
+- Added `attachRequestId()` for explicit `X-Request-Id` response propagation.
+- Added `BCP_LOG_LEVEL=debug|info|warn|error|silent`.
+- Added `BCP_LOG_FORMAT=pretty|json`.
+- Added safe serialization for `Error`, `bigint` and circular structured fields.
+- Development API request logs now flow through the structured logger while framework bootstrap traffic remains filtered.
+- Development module-import and SSR timing lines are normalized into `module.import` and `ssr.render` debug events.
+- Added regression coverage for log filtering, JSON records, error serialization, request-scoped identity and response request IDs.
+
+## Server logger
+
+```ts
+import {
+    logger,
+} from "bcp/server";
+
+logger.info(
+    "User loaded",
+    {
+        userId: 42,
+    }
+);
+```
+
+The default logger reads its level and format from the environment at log time, so normal application configuration can set:
+
+```text
+BCP_LOG_LEVEL=info
+BCP_LOG_FORMAT=json
+```
+
+## Request-scoped logger
+
+```ts
+import {
+    requestLogger,
+} from "bcp/server";
+
+export async function loader() {
+    const log =
+        await requestLogger({
+            feature: "categories",
+        });
+
+    log.info(
+        "Loading categories"
+    );
+
+    return {
+        items: [],
+    };
+}
+```
+
+The child logger binds:
+
+```text
+requestId
+method
+path
+```
+
+using the same request context already used by `requestId()`, `requestMethod()` and `requestUrl()`.
+
+## Request ID response helper
+
+```ts
+import {
+    attachRequestId,
+    json,
+} from "bcp/server";
+
+export async function GET() {
+    return attachRequestId(
+        json({
+            ok: true,
+        })
+    );
+}
+```
+
+The response contains `X-Request-Id` with the active request identity.
+
+## Development observability
+
+Application API request logs retain the existing development noise filter but are now emitted as structured events with:
+
+```text
+event=http.request
+method
+path
+status
+durationMs
+```
+
+SSR and module import measurements are emitted at `debug` level as:
+
+```text
+ssr.render
+module.import
+```
+
+Set `BCP_LOG_LEVEL=debug` when profiling development rendering.
+
+## Stabilization fixes included
+
+The 0.1.23 source line also contains the fixes completed while validating 0.1.22 against `bcp-docs`:
+
+- the `bcp-framework` Windows-safe executable alias avoids the Microsoft SQL Server `bcp.exe` command collision,
+- `<Form>` SSR no longer depends on an implicit global `React` binding under classic JSX transforms,
+- the CLI detects duplicate `bcp` / `@chidchanun/bcp` installations before they produce split React contexts or misleading `useLoaderData()` failures,
+- local release verification guidance uses packed tarballs under the existing `bcp` dependency key so only one framework copy is installed.
+
+## Compatibility
+
+Logging is additive and server-only. Existing rendering, routing, loaders, guards, actions, middleware, validation, database and authentication APIs remain compatible.
+
+Existing application code does not need to adopt the logger to upgrade to 0.1.23.
+
+## Next milestone
+
+The next planned milestone is BCP 0.1.24 — File Upload foundation.

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.22",
+  "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",
@@ -24,7 +24,8 @@
     "node": ">=24.11.0"
   },
   "bin": {
-    "bcp": "packages/cli/bin/bcp.mjs"
+    "bcp": "packages/cli/bin/bcp.mjs",
+    "bcp-framework": "packages/cli/bin/bcp.mjs"
   },
   "exports": {
     ".": {

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/cli/bin/bcp.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+import fs from "node:fs";
+import path from "node:path";
 import {
     spawn,
 } from "node:child_process";
@@ -7,6 +9,46 @@ import {
     fileURLToPath,
 } from "node:url";
 
+const command =
+    process.argv[2] ??
+    "dev";
+
+const duplicateInstall =
+    findDuplicateFrameworkInstall(
+        process.cwd()
+    );
+
+if (duplicateInstall) {
+    const message = [
+        "BCP Framework: duplicate framework installations detected.",
+        "",
+        `bcp: ${duplicateInstall.bcp}`,
+        `@chidchanun/bcp: ${duplicateInstall.scoped}`,
+        "",
+        "The application and the BCP CLI can load different framework copies. This breaks shared React contexts such as useLoaderData() and may produce misleading missing-loader errors.",
+        "",
+        "Keep only one application dependency named bcp. For local tarball verification install it under the bcp dependency key, for example:",
+        "npm install --no-save --package-lock=false \"bcp@file:D:\\\\path\\\\to\\\\chidchanun-bcp-0.1.22.tgz\"",
+    ].join("\n");
+
+    if (
+        command !== "doctor" &&
+        command !== "inspect"
+    ) {
+        console.error(
+            message
+        );
+        process.exitCode =
+            1;
+        process.exit();
+    }
+
+    console.warn(
+        message
+    );
+    console.warn("");
+}
+
 const bootstrapFile =
     fileURLToPath(
         new URL(
@@ -91,3 +133,72 @@ child.once(
             code ?? 1;
     }
 );
+
+function findDuplicateFrameworkInstall(
+    rootDirectory
+) {
+    const bcp =
+        resolvePackageRoot(
+            path.join(
+                rootDirectory,
+                "node_modules",
+                "bcp"
+            )
+        );
+    const scoped =
+        resolvePackageRoot(
+            path.join(
+                rootDirectory,
+                "node_modules",
+                "@chidchanun",
+                "bcp"
+            )
+        );
+
+    if (
+        !bcp ||
+        !scoped ||
+        normalizePath(bcp) ===
+            normalizePath(scoped)
+    ) {
+        return null;
+    }
+
+    return {
+        bcp,
+        scoped,
+    };
+}
+
+function resolvePackageRoot(
+    directory
+) {
+    if (
+        !fs.existsSync(
+            path.join(
+                directory,
+                "package.json"
+            )
+        )
+    ) {
+        return null;
+    }
+
+    try {
+        return fs.realpathSync(
+            directory
+        );
+    } catch {
+        return path.resolve(
+            directory
+        );
+    }
+}
+
+function normalizePath(
+    value
+) {
+    return process.platform === "win32"
+        ? value.toLowerCase()
+        : value;
+}

package/packages/client/src/form.tsx

@@ -1,5 +1,6 @@
 import {
     createContext,
+    createElement,
     useContext,
     useMemo,
     useState,
@@ -320,19 +321,25 @@ export function Form({
             null
         );
 
-    return (
-        <FormRuntimeContext.Provider
-            value={runtimeState}
-        >
-            <form
-                {...props}
-                action={progressiveAction}
-                method="post"
-                onSubmit={handleSubmit}
-            >
-                {children}
-            </form>
-        </FormRuntimeContext.Provider>
+    return createElement(
+        FormRuntimeContext.Provider,
+        {
+            value:
+                runtimeState,
+        },
+        createElement(
+            "form",
+            {
+                ...props,
+                action:
+                    progressiveAction,
+                method:
+                    "post",
+                onSubmit:
+                    handleSubmit,
+            },
+            children
+        )
     );
 }
 

package/packages/client/src/server.ts

@@ -15,6 +15,37 @@ export {
     type ResponseCookieOptions,
 } from "../../server/src/request-context.js";
 
+export {
+    attachRequestId,
+    createLogger,
+    logger,
+    requestLogger,
+    resolveEnvironmentLogFormat,
+    resolveEnvironmentLogLevel,
+
+    type LogFields,
+    type LogFormat,
+    type LogLevel,
+    type Logger,
+    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,