@chidchanun/bcp 0.1.9 → 0.1.10

package/docs/updating.md

@@ -0,0 +1,130 @@
+# Updating BCP Framework
+
+BCP includes a project updater that can move an existing application to a newer published framework version and refresh the active package-manager lockfile.
+
+## First update from 0.1.9 or older
+
+BCP versions published before the updater do not know the `update` command. Run the newest CLI explicitly once:
+
+```bash
+npx @chidchanun/bcp@latest update
+```
+
+The updater adds this project script when the application does not already define its own `update` script:
+
+```json
+{
+  "scripts": {
+    "update": "bcp update"
+  }
+}
+```
+
+Normal future updates can therefore use either:
+
+```bash
+bcp update
+```
+
+or, without a global BCP installation:
+
+```bash
+npm run update
+```
+
+## Update to latest
+
+```bash
+bcp update
+```
+
+This resolves `@chidchanun/bcp@latest` from npm, pins that exact resolved release in `package.json`, detects the project's package manager and runs its install command.
+
+For example, if `latest` resolves to `0.1.10`, a generated application becomes:
+
+```json
+{
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@0.1.10"
+  }
+}
+```
+
+The exact pin is intentional. A later plain `npm install` should not silently move the framework to a release that the BCP updater did not explicitly resolve.
+
+Generated applications use the dependency key `bcp` with an npm alias to `@chidchanun/bcp`. The updater also recognizes a direct `@chidchanun/bcp` dependency.
+
+## Update to a specific version or dist-tag
+
+```bash
+bcp update 0.1.10
+bcp update next
+```
+
+The target may be an exact published version or an npm dist-tag. The updater always records the exact version that the registry resolves.
+
+## Check without changing files
+
+```bash
+bcp update --check
+```
+
+The command resolves the current `latest` target and prints the installed/declaration state without modifying `package.json` or the lockfile.
+
+## Dry run
+
+```bash
+bcp update 0.1.10 --dry-run
+```
+
+A dry run resolves the target and shows the dependency/script changes without writing files or installing packages.
+
+## Project root
+
+Use `--root` when updating a project from another directory:
+
+```bash
+bcp update --root ./apps/admin
+```
+
+## Package-manager detection
+
+BCP detects the package manager from its lockfile:
+
+- `package-lock.json` -> npm
+- `pnpm-lock.yaml` -> pnpm
+- `yarn.lock` -> Yarn
+- `bun.lock` / `bun.lockb` -> Bun
+
+If no lockfile exists, BCP uses the invoking package-manager user agent when available and otherwise falls back to npm. If lockfiles from multiple package managers are present, the updater stops instead of guessing.
+
+Registry version discovery currently uses npm's registry CLI (`npm view`) even when the project itself installs dependencies with pnpm, Yarn or Bun.
+
+## Failure safety
+
+Before installation BCP keeps the original `package.json` and detected lockfile in memory. If the package-manager install fails, those files are restored before the command exits with an error.
+
+A package manager may still have touched `node_modules` before failing, so run the normal install command again after resolving the underlying package-manager or network problem.
+
+## What the updater changes
+
+The updater changes the framework dependency, adds `scripts.update = "bcp update"` when no update script exists, and refreshes the package-manager lockfile. An existing custom `update` script is never overwritten.
+
+It does not overwrite application source code, environment files, authentication implementations, database schemas or custom configuration.
+
+Features that were originally generator presets, such as JWT auth scaffolding, are not automatically injected into an existing application merely by updating the framework package.
+
+## Recommended verification
+
+After an update, run the checks used by your project, for example:
+
+```bash
+npm run typecheck
+npm run build
+```
+
+Commit `package.json` and the lockfile together after verification.
+
+## Release channels
+
+Stable BCP releases use the npm `latest` dist-tag. A release maintainer can still publish an explicit pre-release channel with `BCP_DIST_TAG`, for example `BCP_DIST_TAG=next`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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-guards.ts

@@ -0,0 +1,497 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    fileURLToPath,
+} from "node:url";
+
+import {
+    build,
+} from "esbuild";
+
+import {
+    createServerEnvironmentDefines,
+} from "../../env/src/index.js";
+
+import type {
+    Route,
+} from "../../router/src/index.js";
+
+import {
+    findPageGuardFiles,
+} from "../../server/src/page-guard.js";
+
+export async function buildProductionGuards(
+    pageRoutes: Route[],
+    rootDirectory: string,
+    serverDirectory: string
+): Promise<void> {
+    const outputFile =
+        path.join(
+            serverDirectory,
+            "guards.mjs"
+        );
+
+    fs.rmSync(
+        outputFile,
+        {
+            force: true,
+        }
+    );
+
+    const appDirectory =
+        path.join(
+            rootDirectory,
+            "app"
+        );
+    const guardedRoutes =
+        pageRoutes
+            .map(
+                (route) => ({
+                    route,
+                    guardFiles:
+                        findPageGuardFiles(
+                            appDirectory,
+                            route.filePath
+                        ),
+                })
+            )
+            .filter(
+                (entry) =>
+                    entry.guardFiles.length > 0
+            );
+
+    if (
+        guardedRoutes.length ===
+        0
+    ) {
+        console.log(
+            "[BCP Build] Guards: none"
+        );
+        return;
+    }
+
+    const entryDirectory =
+        path.join(
+            rootDirectory,
+            ".bcp-framework",
+            "build",
+            ".guard-entry"
+        );
+    const entryFile =
+        path.join(
+            entryDirectory,
+            "guards-entry.mjs"
+        );
+
+    fs.rmSync(
+        entryDirectory,
+        {
+            recursive: true,
+            force: true,
+        }
+    );
+    fs.mkdirSync(
+        entryDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    fs.writeFileSync(
+        entryFile,
+        createGuardEntry(
+            guardedRoutes,
+            rootDirectory,
+            entryDirectory
+        ),
+        "utf8"
+    );
+
+    const frameworkDirectory =
+        path.dirname(
+            fileURLToPath(
+                import.meta.url
+            )
+        );
+    const frameworkServerEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/server.ts"
+        );
+    const frameworkServerOnlyEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../client/src/server-only.mjs"
+        );
+    const frameworkCacheEntry =
+        path.resolve(
+            frameworkDirectory,
+            "../../cache/src/index.ts"
+        );
+
+    try {
+        await build({
+            absWorkingDir:
+                rootDirectory,
+            entryPoints: [
+                entryFile,
+            ],
+            outfile:
+                outputFile,
+            bundle:
+                true,
+            platform:
+                "node",
+            format:
+                "esm",
+            target: [
+                "node24",
+            ],
+            minify:
+                process.env
+                    .BCP_BUILD_MINIFY !==
+                "0",
+            sourcemap:
+                process.env
+                    .BCP_BUILD_SOURCE_MAPS ===
+                "1",
+            treeShaking:
+                true,
+            packages:
+                "external",
+            plugins: [
+                {
+                    name:
+                        "bcp-guard-runtime",
+                    setup(buildApi) {
+                        buildApi.onResolve(
+                            {
+                                filter:
+                                    /^bcp\/server$/,
+                            },
+                            () => ({
+                                path:
+                                    frameworkServerEntry,
+                            })
+                        );
+                        buildApi.onResolve(
+                            {
+                                filter:
+                                    /^bcp\/server-only$/,
+                            },
+                            () => ({
+                                path:
+                                    frameworkServerOnlyEntry,
+                            })
+                        );
+                        buildApi.onResolve(
+                            {
+                                filter:
+                                    /^bcp\/cache$/,
+                            },
+                            () => ({
+                                path:
+                                    frameworkCacheEntry,
+                            })
+                        );
+                    },
+                },
+            ],
+            define:
+                createServerEnvironmentDefines(
+                    "production"
+                ),
+            legalComments:
+                "none",
+            logLevel:
+                "silent",
+        });
+    } finally {
+        fs.rmSync(
+            entryDirectory,
+            {
+                recursive: true,
+                force: true,
+            }
+        );
+    }
+
+    console.log(
+        `[BCP Build] Guards: ${guardedRoutes.length} protected route(s) -> ${path.relative(rootDirectory, outputFile).replace(/\\/g, "/")}`
+    );
+}
+
+function createGuardEntry(
+    guardedRoutes: Array<{
+        route: Route;
+        guardFiles: string[];
+    }>,
+    rootDirectory: string,
+    entryDirectory: string
+): string {
+    const frameworkDirectory =
+        path.dirname(
+            fileURLToPath(
+                import.meta.url
+            )
+        );
+    const pageGuardRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../server/src/page-guard.ts"
+        );
+    const requestContextRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../server/src/request-context.ts"
+        );
+    const routerRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../router/src/index.ts"
+        );
+
+    const imports: string[] = [
+        `import { executePageGuardFunctions } from ${JSON.stringify(
+            toImportSpecifier(
+                entryDirectory,
+                pageGuardRuntime
+            )
+        )};`,
+        `import { applyResponseCookies, runWithRequestContext } from ${JSON.stringify(
+            toImportSpecifier(
+                entryDirectory,
+                requestContextRuntime
+            )
+        )};`,
+        `import { matchRoute } from ${JSON.stringify(
+            toImportSpecifier(
+                entryDirectory,
+                routerRuntime
+            )
+        )};`,
+    ];
+    const guardNameByFile =
+        new Map<string, string>();
+    let guardIndex =
+        0;
+
+    for (const entry of guardedRoutes) {
+        for (const guardFile of entry.guardFiles) {
+            if (
+                guardNameByFile.has(
+                    guardFile
+                )
+            ) {
+                continue;
+            }
+
+            const guardName =
+                `Guard${guardIndex++}`;
+            guardNameByFile.set(
+                guardFile,
+                guardName
+            );
+            imports.push(
+                `import { guard as ${guardName} } from ${JSON.stringify(
+                    toImportSpecifier(
+                        entryDirectory,
+                        guardFile
+                    )
+                )};`
+            );
+        }
+    }
+
+    const definitions =
+        guardedRoutes.map(
+            ({
+                route,
+                guardFiles,
+            }) => {
+                const guards =
+                    guardFiles.map(
+                        (guardFile) => {
+                            const guardName =
+                                guardNameByFile.get(
+                                    guardFile
+                                );
+
+                            if (!guardName) {
+                                throw new Error(
+                                    `BCP Framework: guard import was not generated for "${guardFile}".`
+                                );
+                            }
+
+                            const label =
+                                path.relative(
+                                    rootDirectory,
+                                    guardFile
+                                )
+                                    .replace(
+                                        /\\/g,
+                                        "/"
+                                    );
+
+                            return `{
+        filePath: ${JSON.stringify(label)},
+        guard: ${guardName}
+      }`;
+                        }
+                    );
+
+                return `{
+    pathname: ${JSON.stringify(route.pathname)},
+    segments: ${JSON.stringify(route.segments)},
+    guards: [${guards.join(", ")}]
+  }`;
+            }
+        );
+
+    return `${imports.join("\n")}
+
+const definitions = [
+  ${definitions.join(",\n  ")}
+];
+
+const routePatterns =
+  definitions.map(
+    (definition) => ({
+      pathname:
+        definition.pathname,
+      segments:
+        definition.segments,
+      filePath:
+        definition.pathname,
+      layouts: []
+    })
+  );
+
+const definitionByPathname =
+  new Map(
+    definitions.map(
+      (definition) => [
+        definition.pathname,
+        definition
+      ]
+    )
+  );
+
+export const guardedPathnames =
+  definitions.map(
+    (definition) =>
+      definition.pathname
+  );
+
+export async function evaluateRouteGuards(input) {
+  const target =
+    new URL(
+      input.url
+    );
+  const match =
+    matchRoute(
+      routePatterns,
+      target.pathname
+    );
+
+  if (!match) {
+    return null;
+  }
+
+  const definition =
+    definitionByPathname.get(
+      match.route.pathname
+    );
+
+  if (!definition) {
+    return null;
+  }
+
+  const request =
+    new Request(
+      target,
+      {
+        method:
+          input.method ||
+          "GET",
+        headers:
+          new Headers(
+            input.headers ||
+            []
+          )
+      }
+    );
+
+  return runWithRequestContext(
+    request,
+    async () => {
+      const execution =
+        await executePageGuardFunctions(
+          definition.guards,
+          match.params,
+          target
+        );
+
+      if (execution.response) {
+        return {
+          kind:
+            "response",
+          response:
+            applyResponseCookies(
+              execution.response
+            )
+        };
+      }
+
+      const cookieCarrier =
+        applyResponseCookies(
+          new Response(
+            null,
+            {
+              status: 204
+            }
+          )
+        );
+
+      return {
+        kind:
+          "allow",
+        data:
+          execution.data,
+        setCookies:
+          cookieCarrier.headers.getSetCookie()
+      };
+    },
+    {
+      remoteAddress:
+        input.remoteAddress ||
+        null
+    }
+  );
+}
+`;
+}
+
+function toImportSpecifier(
+    fromDirectory: string,
+    filePath: string
+): string {
+    let relative =
+        path.relative(
+            fromDirectory,
+            filePath
+        )
+            .replace(
+                /\\/g,
+                "/"
+            );
+
+    if (
+        !relative.startsWith(".")
+    ) {
+        relative =
+            `./${relative}`;
+    }
+
+    return relative;
+}

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

@@ -16,6 +16,10 @@ import {
     findProjectMiddlewareFile,
 } from "../../server/src/middleware-loader.js";
 
+import {
+    routeHasPageGuard,
+} from "../../server/src/page-guard.js";
+
 import type {
     ApiRoute,
     Route,
@@ -29,6 +33,10 @@ import type {
     PartialHydrationBuildManifest,
 } from "./partial-hydration.js";
 
+import {
+    buildProductionGuards,
+} from "./server-production-guards.js";
+
 import {
     buildProductionServer as buildBaseProductionServer,
     type ProductionServerBuildResult,
@@ -73,7 +81,8 @@ export async function buildProductionServer(
     writeCacheManifest(
         pageRoutes,
         apiRoutes,
-        serverDirectory
+        serverDirectory,
+        rootDirectory
     );
 
     await buildProductionMiddleware(
@@ -81,6 +90,12 @@ export async function buildProductionServer(
         serverDirectory
     );
 
+    await buildProductionGuards(
+        pageRoutes,
+        rootDirectory,
+        serverDirectory
+    );
+
     return {
         ...baseResult,
         size:
@@ -174,11 +189,6 @@ async function bundleServerCacheRuntime(
             serverFile
         );
 
-        /*
-         * The base server build may have emitted an external map. The final
-         * cache-runtime rebundle uses an inline map so a stale server.mjs.map
-         * must not be shipped next to the rewritten bundle.
-         */
         fs.rmSync(
             `${serverFile}.map`,
             {
@@ -204,14 +214,29 @@ async function bundleServerCacheRuntime(
 function writeCacheManifest(
     pageRoutes: Route[],
     apiRoutes: ApiRoute[],
-    serverDirectory: string
+    serverDirectory: string,
+    rootDirectory: string
 ): void {
+    const appDirectory =
+        path.join(
+            rootDirectory,
+            "app"
+        );
+    const cacheablePages =
+        pageRoutes.filter(
+            (route) =>
+                !routeHasPageGuard(
+                    appDirectory,
+                    route.filePath
+                )
+        );
+
     const manifest:
         CacheManifest = {
         version: 1,
         pages:
             collectCacheRoutes(
-                pageRoutes
+                cacheablePages
             ),
         apiRoutes:
             collectCacheRoutes(