@bractjs/bractjs 0.1.22 → 0.1.24

package/src/server/request-handler.ts

@@ -1,7 +1,7 @@
 import { createElement } from "react";
 import type { TrieNode } from "./matcher.ts";
 import { matchRoute } from "./matcher.ts";
-import { resolveRouteChain } from "./layout.ts";
+import { resolveRouteChain, type ModuleRegistry } from "./layout.ts";
 import { runLoaders, runAction, buildLoaderArgs, runRouteContext, runBeforeLoad } from "./loader.ts";
 import { renderRoute, type ServerManifest } from "./render.ts";
 import { resolveMeta } from "./meta.ts";
@@ -11,11 +11,19 @@ import { isExplicitDev } from "./env.ts";
 import { pipeline, type MiddlewareContext } from "./middleware.ts";
 import { BractJSProvider } from "../shared/context.ts";
 import { isAllowedMutation } from "./csrf.ts";
+import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
 export interface HandlerConfig {
   appDir: string;
   publicDir: string;
   manifest: ServerManifest;
+  onError?: OnErrorHook;
+  /**
+   * Pre-loaded route/layout/root modules keyed by appDir-relative path.
+   * Provided by codegen (`_generated/routes.ts`) for compiled binaries
+   * where dynamic `import(absPath)` is unavailable. Falsy in dev mode.
+   */
+  moduleRegistry?: ModuleRegistry;
 }
 
 const MUTATING_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
@@ -45,7 +53,7 @@ async function route(
   config: HandlerConfig,
   context: Record<string, unknown>,
 ): Promise<Response> {
-  const { appDir, manifest } = config;
+  const { appDir, manifest, onError, moduleRegistry } = config;
   const url = new URL(request.url);
   const { pathname, searchParams } = url;
 
@@ -68,7 +76,7 @@ async function route(
     if (!match) return json({ error: "Not Found" }, { status: 404 });
 
     try {
-      const chain = await resolveRouteChain(match.routeFile, appDir);
+      const chain = await resolveRouteChain(match.routeFile, appDir, moduleRegistry);
       // Reconstruct a Request that carries the original search params so loaders
       // can access them via request.url / new URL(request.url).searchParams.
       const targetUrl = new URL(request.url);
@@ -90,12 +98,13 @@ async function route(
       const args = buildLoaderArgs(loaderRequest, match.params, routeContext);
       const beforeLoadResponse = await runBeforeLoad(chain.route, args);
       if (beforeLoadResponse) return beforeLoadResponse;
-      const results = await runLoaders(chain, args);
+      const results = await runLoaders(chain, args, onError);
       return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params });
     } catch (err) {
       if (isRedirect(err)) return err as Response;
       if (isHttpError(err)) return json({ error: err.message }, { status: err.status });
       console.error("[bractjs] /_data error:", err);
+      await fireOnError(onError, err, request);
       return json({ error: "Internal Server Error" }, { status: 500 });
     }
   }
@@ -104,7 +113,7 @@ async function route(
   const match = matchRoute(pathname, trie);
   if (!match) return error("Not Found", 404);
 
-  const chain = await resolveRouteChain(match.routeFile, appDir);
+  const chain = await resolveRouteChain(match.routeFile, appDir, moduleRegistry);
   // Run per-route context factory (defineContext export) before loaders.
   const routeContext = await runRouteContext(
     chain.route as Parameters<typeof runRouteContext>[0],
@@ -138,6 +147,7 @@ async function route(
     } catch (err) {
       if (isRedirect(err)) return err as Response;
       if (isHttpError(err)) return error(err.message, err.status);
+      await fireOnError(onError, err, request);
       if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
       return error("Internal Server Error", 500);
     }
@@ -151,10 +161,11 @@ async function route(
   // ── Loaders ───────────────────────────────────────────────────────────
   let loaderResults;
   try {
-    loaderResults = await runLoaders(chain, args);
+    loaderResults = await runLoaders(chain, args, onError);
   } catch (err) {
     if (isRedirect(err)) return err as Response;
     if (isHttpError(err)) return error(err.message, err.status);
+    await fireOnError(onError, err, request);
     if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
     return error("Internal Server Error", 500);
   }

package/src/server/serve.ts

@@ -1,4 +1,4 @@
-import { scanRoutes } from "./scanner.ts";
+import { scanRoutes, type RouteFile } from "./scanner.ts";
 import { buildTrie } from "./matcher.ts";
 import { handleRequest, type HandlerConfig } from "./request-handler.ts";
 import { type ServerManifest } from "./render.ts";
@@ -6,10 +6,12 @@ import { isDevRuntime, isExplicitDev } from "./env.ts";
 import { loadManifest } from "../build/manifest.ts";
 import { serveStatic } from "./static.ts";
 import { handleImageRequest } from "../image/handler.ts";
-import { loadServerActions } from "./action-registry.ts";
+import { loadServerActions, loadServerActionsFromRegistry } from "./action-registry.ts";
 import { handleActionRequest } from "./action-handler.ts";
 import { BunAdapter, type BractAdapter } from "./adapter.ts";
+import type { ModuleRegistry } from "./layout.ts";
 import { resolve, join } from "node:path";
+import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
 export interface I18nConfig {
   locales: string[];
@@ -38,6 +40,27 @@ export interface BractJSConfig {
   onStart?: () => Promise<void> | void;
   /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
   onShutdown?: () => Promise<void> | void;
+  /** Called for every unexpected error: loader failures, action throws, and uncaught process exceptions. Redirects and HttpErrors are intentional control flow and are NOT reported here. The request is undefined for process-level exceptions. */
+  onError?: OnErrorHook;
+  /**
+   * Pre-scanned route list (typically exported from `app/_generated/routes.ts`).
+   * When provided, skips the startup `Bun.Glob` scan of `appDir`. Required for
+   * `bun build --compile` binaries where the embedded filesystem has no
+   * scannable routes/ directory.
+   */
+  routeFiles?: RouteFile[];
+  /**
+   * Pre-loaded route/layout/root modules keyed by appDir-relative path.
+   * Required alongside `routeFiles` for compiled binaries — `resolveRouteChain`
+   * uses this map instead of `import(absPath)` at request time.
+   */
+  moduleRegistry?: ModuleRegistry;
+  /**
+   * Pre-imported server-action modules (typically `app/_generated/actions.ts`).
+   * When provided, skips the startup `Bun.Glob` scan + dynamic import that
+   * `loadServerActions` does.
+   */
+  actionModules?: Array<{ relPath: string; mod: Record<string, unknown> }>;
 }
 
 const DEFAULT_MANIFEST: ServerManifest = {
@@ -84,8 +107,18 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
       }))
     : Promise.resolve(config.manifest ?? DEFAULT_MANIFEST);
 
-  const trieReady = scanRoutes(appDir).then(buildTrie);
-  const actionsReady = loadServerActions(appDir);
+  // Codegen / compiled-binary path: when the caller supplies pre-scanned
+  // routes, skip the runtime `Bun.Glob` scan that `bun build --compile`
+  // can't satisfy (the routes/ directory isn't on the filesystem in a
+  // single-binary deployment). Same idea for server actions.
+  const trieReady = config.routeFiles
+    ? Promise.resolve(buildTrie(config.routeFiles))
+    : scanRoutes(appDir).then(buildTrie);
+  const actionsReady = config.actionModules
+    ? loadServerActionsFromRegistry(config.actionModules)
+    : loadServerActions(appDir);
+  const moduleRegistry = config.moduleRegistry;
+  const onError = config.onError;
 
   return async function fetch(request: Request): Promise<Response> {
     const url = new URL(request.url);
@@ -154,7 +187,7 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
 
     const trie = await trieReady;
     const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
-    const handlerConfig: HandlerConfig = { appDir, publicDir, manifest };
+    const handlerConfig: HandlerConfig = { appDir, publicDir, manifest, onError, moduleRegistry };
     return handleRequest(request, trie, handlerConfig);
   };
 }
@@ -186,6 +219,7 @@ async function warnIfStaleBuild(buildDir: string): Promise<void> {
 let signalsRegistered = false;
 let isShuttingDown = false;
 let activeOnShutdown: (() => Promise<void> | void) | undefined;
+let activeOnError: OnErrorHook | undefined;
 
 export function createServer(config?: Partial<BractJSConfig>): {
   stop(): void;
@@ -213,6 +247,7 @@ export function createServer(config?: Partial<BractJSConfig>): {
   }
 
   activeOnShutdown = config?.onShutdown;
+  activeOnError = config?.onError;
 
   console.log(`[bract] Server running at http://localhost:${port}`);
 
@@ -224,37 +259,46 @@ export function createServer(config?: Partial<BractJSConfig>): {
     }
   };
 
-  const gracefulShutdown = (signal?: string) => {
+  // Programmatic / beforeExit path — runs the user hook, stops the adapter,
+  // and returns. Does NOT call process.exit() so callers (tests, parent
+  // supervisors) can keep running. `gracefulShutdown` below wraps this and
+  // adds an explicit exit for signal handlers, where termination is the
+  // whole point.
+  const shutdownOnce = async (signal?: string): Promise<void> => {
     if (isShuttingDown) return;
     isShuttingDown = true;
     if (signal) console.log(`\n[bract] Received ${signal}, shutting down…`);
     try {
       const result = activeOnShutdown?.();
       if (result instanceof Promise) {
-        result.catch((err) => console.error("[bract] onShutdown error:", err)).finally(() => {
-          stopAdapter();
-          process.exit(0);
-        });
-      } else {
-        stopAdapter();
-        process.exit(0);
+        try { await result; }
+        catch (err) { console.error("[bract] onShutdown error:", err); }
       }
     } catch (err) {
       console.error("[bract] onShutdown error:", err);
+    } finally {
       stopAdapter();
-      process.exit(1);
     }
   };
 
+  const gracefulShutdown = (signal?: string, exitCode = 0): void => {
+    void shutdownOnce(signal).finally(() => process.exit(exitCode));
+  };
+
   if (!signalsRegistered) {
     signalsRegistered = true;
     process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
     process.on("SIGINT",  () => gracefulShutdown("SIGINT"));
     process.on("SIGUSR2", () => gracefulShutdown("SIGUSR2"));
-    process.on("beforeExit", () => gracefulShutdown());
+    // `beforeExit` fires when the event loop is naturally draining — we
+    // already shut down the adapter at that point, but we must NOT call
+    // process.exit(). Doing so re-enters the lifecycle and prevents test
+    // runners (and any parent process supervising us) from observing a
+    // clean exit code. Just run the user hook + stop the listener.
+    process.on("beforeExit", () => { void shutdownOnce(); });
     process.on("uncaughtException", (err) => {
       console.error("[bract] Uncaught exception:", err);
-      gracefulShutdown("uncaughtException");
+      void fireOnError(activeOnError, err).then(() => gracefulShutdown("uncaughtException", 1));
     });
   }
 
@@ -263,7 +307,12 @@ export function createServer(config?: Partial<BractJSConfig>): {
   });
 
   return {
-    stop() { void gracefulShutdown(); },
+    // Programmatic stop — runs `onShutdown`, then closes the listener. Does
+    // NOT call `process.exit()`. Tests rely on this so the runner can print
+    // its summary; long-running supervisors rely on it so a stop() doesn't
+    // tear down the whole worker. Use SIGTERM/SIGINT if you actually want
+    // the process to exit.
+    stop() { void shutdownOnce(); },
   };
 }
 

package/src/server/static.ts

@@ -4,20 +4,40 @@ import { realpath } from "node:fs/promises";
 const IMMUTABLE = "public, max-age=31536000, immutable";
 const NO_CACHE = "no-cache";
 
-// Resolve to a canonical path that follows symlinks. Returns null if the
-// target doesn't exist OR escapes the given root after symlink expansion.
+/**
+ * Resolve to a canonical path that follows symlinks, with a fallback for
+ * `bun build --compile` binaries.
+ *
+ * Three outcomes:
+ * 1. realpath succeeds + stays inside `root` → return resolved path
+ * 2. realpath throws AND `Bun.file(candidate)` exists → return the candidate
+ *    path. This is the embedded-asset case: `bun --compile` exposes assets
+ *    through virtual paths that don't appear in the filesystem, so realpath
+ *    errors with ENOENT/EINVAL but `Bun.file()` still reads them.
+ * 3. otherwise → null (escape, ENOENT, etc.)
+ *
+ * The structural `startsWith(root + sep)` check at the top runs before any
+ * I/O and is the authoritative traversal guard — the realpath check is
+ * defense-in-depth against symlink escape, which can't happen inside an
+ * embedded virtual filesystem.
+ */
 async function safeRealpath(root: string, requested: string): Promise<string | null> {
   const candidate = resolve(join(root, requested));
-  // Cheap structural reject before touching the FS.
+  // Cheap structural reject before touching the FS. This blocks `..` escapes
+  // unconditionally, in both the normal-FS and embedded-binary paths.
   if (!candidate.startsWith(root + sep) && candidate !== root) return null;
-  let real: string;
   try {
-    real = await realpath(candidate);
+    const real = await realpath(candidate);
+    if (!real.startsWith(root + sep) && real !== root) return null;
+    return real;
   } catch {
+    // realpath fails for paths embedded by `bun build --compile --asset`.
+    // The structural check above already prevented traversal, so the only
+    // remaining concern is whether the asset actually exists — defer to
+    // Bun.file() which reads from the embed table.
+    if (await Bun.file(candidate).exists()) return candidate;
     return null;
   }
-  if (!real.startsWith(root + sep) && real !== root) return null;
-  return real;
 }
 
 /**

package/templates/new-app/app/server.ts

@@ -0,0 +1,30 @@
+// Entry point for `bun build --compile`.
+//
+// Pre-generated registries below come from `bractjs codegen:registry` and
+// `bractjs codegen:manifest`. They turn every runtime fs scan / dynamic
+// import the framework would normally do into static, traceable imports so
+// `bun build --compile` can produce a single executable.
+//
+// Generate-then-compile:
+//   bractjs codegen:registry             # writes routes.ts + actions.ts
+//   bractjs build                        # writes build/client/* + manifest
+//   bractjs codegen:manifest             # snapshots manifest into TS
+//   bun build --compile app/server.ts --outfile myapp [--asset build/client/]
+//
+// Or run all of the above in one shot:
+//   bractjs compile
+
+import { createServer } from "@bractjs/bractjs";
+import { routeFiles, moduleRegistry } from "./_generated/routes.ts";
+import { actionModules } from "./_generated/actions.ts";
+import { manifest } from "./_generated/manifest.ts";
+
+createServer({
+  port: Number(process.env.PORT ?? 3000),
+  appDir: "./app",
+  publicDir: "./public",
+  manifest,
+  routeFiles,
+  moduleRegistry,
+  actionModules,
+});

package/templates/new-app/package.json

@@ -5,7 +5,8 @@
   "scripts": {
     "dev": "bractjs dev",
     "build": "NODE_ENV=production bractjs build",
-    "start": "NODE_ENV=production bractjs start"
+    "start": "NODE_ENV=production bractjs start",
+    "compile": "NODE_ENV=production bractjs compile"
   },
   "dependencies": {
     "@bractjs/bractjs": "latest",

package/types/config.d.ts

@@ -1,4 +1,5 @@
 import type { BunPlugin } from "bun";
+import type { RouteFile, RouteModule } from "./route.d.ts";
 
 export interface BractJSConfig {
   /** TCP port to listen on. Default: 3000. */
@@ -23,13 +24,32 @@ export interface BractJSConfig {
   onStart?: () => Promise<void> | void;
   /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
   onShutdown?: () => Promise<void> | void;
+  /**
+   * Pre-scanned route list. Typically imported from `app/_generated/routes.ts`.
+   * Required for `bun build --compile` binaries where the routes/ directory
+   * isn't on a scannable filesystem.
+   */
+  routeFiles?: RouteFile[];
+  /**
+   * Pre-loaded route/layout/root modules keyed by appDir-relative path.
+   * Typically imported from `app/_generated/routes.ts`.
+   */
+  moduleRegistry?: Record<string, RouteModule | Record<string, unknown>>;
+  /**
+   * Pre-imported server-action modules. Typically imported from
+   * `app/_generated/actions.ts`. Each `relPath` MUST match what the client
+   * proxy plugin hashed during the client build.
+   */
+  actionModules?: Array<{ relPath: string; mod: Record<string, unknown> }>;
 }
 
 export interface ServerManifest {
   /** Hashed path to the main client entry bundle. */
   clientEntry: string;
+  /** Hashed path to the root.tsx chunk (when emitted as a separate entry). */
+  rootChunk?: string;
   /** Map of URL pattern → route asset info. */
-  routes: Record<string, { file?: string; chunk?: string }>;
+  routes: Record<string, { file?: string; chunk?: string; imports?: string[] }>;
 }
 
 /** Subset of BractJSConfig used by the build pipeline. All fields optional. */

package/types/index.d.ts

@@ -4,6 +4,7 @@ import type { ReactNode, Context } from "react";
 export type {
   LoaderArgs, ActionArgs, MetaDescriptor, MetaArgs,
   LoaderFunction, ActionFunction, MetaFunction, RouteModule,
+  RouteFile, Segment,
 } from "./route.d.ts";
 
 // ── Config + Server ───────────────────────────────────────────────────────
@@ -22,9 +23,13 @@ export interface RenderOptions {
   status?: number;
 }
 
+export type OnErrorHook = (err: unknown, request?: Request) => Promise<void> | void;
+
 export interface LifecycleHooks {
   onStart?: () => Promise<void> | void;
   onShutdown?: () => Promise<void> | void;
+  /** Called for every unexpected error: loader failures, action throws, and uncaught process exceptions. Redirects and HttpErrors are NOT reported here. The request is undefined for process-level exceptions. */
+  onError?: OnErrorHook;
 }
 export declare function defineLifecycle(hooks: LifecycleHooks): LifecycleHooks;
 export declare function createServer(config?: Partial<BractJSConfig>): { stop(): void };
@@ -203,6 +208,34 @@ export declare function makeCloudflareHandler(
 export declare const cssModulesPlugin: unknown; // BunPlugin
 export declare function transformCssModule(filePath: string): Promise<{ map: Record<string, string>; css: string }>;
 
+// ── Build plugins (required for native `bun build --compile` workflow) ───
+//
+// Apply all of these on the relevant bundle or face crashes / secret leaks:
+//   server bundle  → useClientStubPlugin
+//   client bundle  → createUseServerProxyPlugin(appDir), serverOnlyPlugin,
+//                    clientEnvPlugin(allowedKeys, env), cssModulesPlugin
+export declare const useClientStubPlugin: unknown; // BunPlugin
+export declare function createUseServerProxyPlugin(appDir?: string): unknown; // BunPlugin
+export declare const useServerProxyPlugin: unknown; // BunPlugin (legacy — uses absolute paths)
+export declare const serverOnlyPlugin: unknown; // BunPlugin
+export declare function clientEnvPlugin(
+  allowedKeys: string[],
+  envValues: Record<string, string>,
+): unknown; // BunPlugin
+
+// ── Module-registry codegen (drives `bun build --compile`) ────────────────
+export interface CodegenResult {
+  routesPath: string;
+  actionsPath: string;
+}
+/** Scan appDir; write `<appDir>/_generated/routes.ts` and `actions.ts`. */
+export declare function writeModuleRegistries(appDir: string): Promise<CodegenResult>;
+/** Read `<buildDir>/route-manifest.json`; write `<appDir>/_generated/manifest.ts`. */
+export declare function writeManifestModule(appDir: string, buildDir: string): Promise<string>;
+
+/** Pre-loaded route/layout/root modules keyed by appDir-relative path. */
+export type ModuleRegistry = Record<string, import("./route.d.ts").RouteModule | Record<string, unknown>>;
+
 // ── buildFetchHandler (D1) ───────────────────────────────────────────────
 export declare function buildFetchHandler(config: Partial<import("./config.d.ts").BractJSConfig>): (request: Request) => Promise<Response>;
 

package/types/route.d.ts

@@ -50,3 +50,11 @@ export interface RouteModule<TLoader = unknown, TAction = unknown> {
   ErrorBoundary?: ComponentType<{ error: unknown }>;
   default?: ComponentType;
 }
+
+export type Segment = string | { param: string } | { catchAll: string };
+
+export interface RouteFile {
+  filePath: string;
+  urlPattern: string;
+  segments: Segment[];
+}

package/src/__tests__/.tmp-security-action/routes/_index.tsx

@@ -1,2 +0,0 @@
-"use server";
-export async function ping(...args) { return args; }