@chidchanun/bcp 0.1.9 → 0.1.11

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.11",
   "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

@@ -0,0 +1,523 @@
+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";
+
+import {
+    findPageActionFile,
+} from "../../server/src/form-action.js";
+
+export async function buildProductionActions(
+    pageRoutes: Route[],
+    rootDirectory: string,
+    serverDirectory: string
+): Promise<void> {
+    const outputFile =
+        path.join(
+            serverDirectory,
+            "actions.mjs"
+        );
+
+    fs.rmSync(
+        outputFile,
+        {
+            force: true,
+        }
+    );
+
+    const appDirectory =
+        path.join(
+            rootDirectory,
+            "app"
+        );
+    const actionRoutes =
+        pageRoutes
+            .map(
+                (route) => ({
+                    route,
+                    actionFile:
+                        findPageActionFile(
+                            route.filePath
+                        ),
+                    guardFiles:
+                        findPageGuardFiles(
+                            appDirectory,
+                            route.filePath
+                        ),
+                })
+            )
+            .filter(
+                (entry) =>
+                    entry.actionFile !==
+                    null
+            ) as Array<{
+                route: Route;
+                actionFile: string;
+                guardFiles: string[];
+            }>;
+
+    if (
+        actionRoutes.length ===
+        0
+    ) {
+        console.log(
+            "[BCP Build] Actions: none"
+        );
+        return;
+    }
+
+    const entryDirectory =
+        path.join(
+            rootDirectory,
+            ".bcp-framework",
+            "build",
+            ".action-entry"
+        );
+    const entryFile =
+        path.join(
+            entryDirectory,
+            "actions-entry.mjs"
+        );
+
+    fs.rmSync(
+        entryDirectory,
+        {
+            recursive: true,
+            force: true,
+        }
+    );
+    fs.mkdirSync(
+        entryDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    fs.writeFileSync(
+        entryFile,
+        createActionEntry(
+            actionRoutes,
+            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-action-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] Actions: ${actionRoutes.length} route(s) -> ${path.relative(rootDirectory, outputFile).replace(/\\/g, "/")}`
+    );
+}
+
+function createActionEntry(
+    actionRoutes: Array<{
+        route: Route;
+        actionFile: string;
+        guardFiles: string[];
+    }>,
+    rootDirectory: string,
+    entryDirectory: string
+): string {
+    const frameworkDirectory =
+        path.dirname(
+            fileURLToPath(
+                import.meta.url
+            )
+        );
+    const actionRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../server/src/form-action.ts"
+        );
+    const actionTransportRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../server/src/form-action-transport.ts"
+        );
+    const guardRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../server/src/page-guard.ts"
+        );
+    const requestContextRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../server/src/request-context.ts"
+        );
+    const cacheRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../cache/src/index.ts"
+        );
+    const routerRuntime =
+        path.resolve(
+            frameworkDirectory,
+            "../../router/src/index.ts"
+        );
+
+    const imports: string[] = [
+        `import { assertPageActionName, executePageActionFunction, normalizePageActionMethod } from ${JSON.stringify(toImportSpecifier(entryDirectory, actionRuntime))};`,
+        `import { completePageActionExecution } from ${JSON.stringify(toImportSpecifier(entryDirectory, actionTransportRuntime))};`,
+        `import { executePageGuardFunctions } from ${JSON.stringify(toImportSpecifier(entryDirectory, guardRuntime))};`,
+        `import { runWithRequestContext } from ${JSON.stringify(toImportSpecifier(entryDirectory, requestContextRuntime))};`,
+        `import { runWithRequestCacheContext } from ${JSON.stringify(toImportSpecifier(entryDirectory, cacheRuntime))};`,
+        `import { matchRoute } from ${JSON.stringify(toImportSpecifier(entryDirectory, routerRuntime))};`,
+    ];
+    const guardNameByFile =
+        new Map<string, string>();
+    let guardIndex =
+        0;
+
+    actionRoutes.forEach(
+        (entry, index) => {
+            imports.push(
+                `import * as Actions${index} from ${JSON.stringify(toImportSpecifier(entryDirectory, entry.actionFile))};`
+            );
+
+            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 =
+        actionRoutes.map(
+            (entry, index) => {
+                const guards =
+                    entry.guardFiles.map(
+                        (guardFile) => {
+                            const guardName =
+                                guardNameByFile.get(
+                                    guardFile
+                                );
+
+                            if (!guardName) {
+                                throw new Error(
+                                    `BCP Framework: action guard import was not generated for "${guardFile}".`
+                                );
+                            }
+
+                            return `{
+        filePath: ${JSON.stringify(path.relative(rootDirectory, guardFile).replace(/\\/g, "/"))},
+        guard: ${guardName}
+      }`;
+                        }
+                    );
+
+                return `{
+    pathname: ${JSON.stringify(entry.route.pathname)},
+    segments: ${JSON.stringify(entry.route.segments)},
+    actions: Actions${index},
+    actionFile: ${JSON.stringify(path.relative(rootDirectory, entry.actionFile).replace(/\\/g, "/"))},
+    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 actionPathnames =
+  definitions.map(
+    (definition) =>
+      definition.pathname
+  );
+
+export async function evaluateRouteAction(input) {
+  assertPageActionName(
+    input.name
+  );
+
+  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 candidate =
+    definition.actions[
+      input.name
+    ];
+
+  if (
+    typeof candidate !==
+    "function"
+  ) {
+    return null;
+  }
+
+  const method =
+    normalizePageActionMethod(
+      input.method
+    );
+  const request =
+    new Request(
+      target,
+      {
+        method,
+        headers:
+          new Headers(
+            input.headers ||
+            []
+          )
+      }
+    );
+
+  return runWithRequestContext(
+    request,
+    () =>
+      runWithRequestCacheContext(
+        target.pathname,
+        async () => {
+          const guardExecution =
+            await executePageGuardFunctions(
+              definition.guards,
+              match.params,
+              target
+            );
+
+          if (guardExecution.response) {
+            return completePageActionExecution({
+              hasGuard:
+                guardExecution.hasGuard,
+              guardData:
+                guardExecution.data,
+              data:
+                null,
+              response:
+                guardExecution.response
+            });
+          }
+
+          const execution =
+            await executePageActionFunction(
+              candidate,
+              input.name,
+              method,
+              input.formData,
+              match.params,
+              target,
+              guardExecution.data,
+              guardExecution.hasGuard,
+              definition.actionFile
+            );
+
+          return completePageActionExecution(
+            execution
+          );
+        }
+      ),
+    {
+      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;
+}