@btst/stack 2.4.0 → 2.5.0

package/src/plugins/kanban/client/plugin.tsx

@@ -2,6 +2,7 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -86,39 +87,39 @@ export interface KanbanClientConfig {
  */
 export interface KanbanClientHooks {
 	/**
-	 * Called before loading boards list. Return false to cancel loading.
+	 * Called before loading boards list. Throw an error to cancel loading.
 	 */
-	beforeLoadBoards?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadBoards?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called after boards are loaded. Return false to cancel further processing.
+	 * Called after boards are loaded. Throw an error to cancel further processing.
 	 */
 	afterLoadBoards?: (
 		boards: SerializedBoardWithColumns[] | null,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before loading a single board. Return false to cancel loading.
+	 * Called before loading a single board. Throw an error to cancel loading.
 	 */
 	beforeLoadBoard?: (
 		boardId: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called after a board is loaded. Return false to cancel further processing.
+	 * Called after a board is loaded. Throw an error to cancel further processing.
 	 */
 	afterLoadBoard?: (
 		board: SerializedBoardWithColumns | null,
 		boardId: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before loading the new board page. Return false to cancel.
+	 * Called before loading the new board page. Throw an error to cancel.
 	 */
-	beforeLoadNewBoard?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadNewBoard?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called after the new board page is loaded. Return false to cancel.
+	 * Called after the new board page is loaded. Throw an error to cancel.
 	 */
-	afterLoadNewBoard?: (context: LoaderContext) => Promise<boolean> | boolean;
+	afterLoadNewBoard?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called when a loading error occurs
 	 */
@@ -141,10 +142,10 @@ function createBoardsLoader(config: KanbanClientConfig) {
 
 			try {
 				if (hooks?.beforeLoadBoards) {
-					const canLoad = await hooks.beforeLoadBoards(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadBoards hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadBoards!(context),
+						"Load prevented by beforeLoadBoards hook",
+					);
 				}
 
 				const client = createApiClient<KanbanApiRouter>({
@@ -161,13 +162,10 @@ function createBoardsLoader(config: KanbanClientConfig) {
 					const boards = queryClient.getQueryData<SerializedBoardWithColumns[]>(
 						listQuery.queryKey,
 					);
-					const canContinue = await hooks.afterLoadBoards(
-						boards || null,
-						context,
+					await runClientHookWithShim(
+						() => hooks.afterLoadBoards!(boards || null, context),
+						"Load prevented by afterLoadBoards hook",
 					);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadBoards hook");
-					}
 				}
 
 				const queryState = queryClient.getQueryState(listQuery.queryKey);
@@ -210,10 +208,10 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 
 			try {
 				if (hooks?.beforeLoadBoard) {
-					const canLoad = await hooks.beforeLoadBoard(boardId, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadBoard hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadBoard!(boardId, context),
+						"Load prevented by beforeLoadBoard hook",
+					);
 				}
 
 				const client = createApiClient<KanbanApiRouter>({
@@ -229,14 +227,10 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 					const board = queryClient.getQueryData<SerializedBoardWithColumns>(
 						boardQuery.queryKey,
 					);
-					const canContinue = await hooks.afterLoadBoard(
-						board || null,
-						boardId,
-						context,
+					await runClientHookWithShim(
+						() => hooks.afterLoadBoard!(board || null, boardId, context),
+						"Load prevented by afterLoadBoard hook",
 					);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadBoard hook");
-					}
 				}
 
 				const queryState = queryClient.getQueryState(boardQuery.queryKey);
@@ -278,17 +272,17 @@ function createNewBoardLoader(config: KanbanClientConfig) {
 
 			try {
 				if (hooks?.beforeLoadNewBoard) {
-					const canLoad = await hooks.beforeLoadNewBoard(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadNewBoard hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadNewBoard!(context),
+						"Load prevented by beforeLoadNewBoard hook",
+					);
 				}
 
 				if (hooks?.afterLoadNewBoard) {
-					const canContinue = await hooks.afterLoadNewBoard(context);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadNewBoard hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.afterLoadNewBoard!(context),
+						"Load prevented by afterLoadNewBoard hook",
+					);
 				}
 			} catch (error) {
 				if (hooks?.onLoadError) {

package/src/plugins/ui-builder/client/plugin.tsx

@@ -3,6 +3,7 @@ import { lazy } from "react";
 import {
 	defineClientPlugin,
 	createApiClient,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -69,10 +70,10 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadPageList) {
-					const canLoad = await hooks.beforeLoadPageList(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPageList hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPageList!(context),
+						"Load prevented by beforeLoadPageList hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -161,10 +162,10 @@ function createPageBuilderLoader(
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadPageBuilder) {
-					const canLoad = await hooks.beforeLoadPageBuilder(id, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPageBuilder hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPageBuilder!(id, context),
+						"Load prevented by beforeLoadPageBuilder hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -273,11 +274,11 @@ function createPageBuilderMeta(
  *   hooks: {
  *     beforeLoadPageList: async (ctx) => {
  *       const session = await getSession(ctx.headers)
- *       return session?.user?.isAdmin === true
+ *       if (!session?.user?.isAdmin) throw new Error("Admin access required")
  *     },
  *     beforeLoadPageBuilder: async (pageId, ctx) => {
  *       const session = await getSession(ctx.headers)
- *       return session?.user?.isAdmin === true
+ *       if (!session?.user?.isAdmin) throw new Error("Admin access required")
  *     },
  *     onLoadError: () => redirect("/auth/sign-in"),
  *   },

package/src/plugins/ui-builder/types.ts

@@ -92,24 +92,24 @@ export interface LoaderContext {
  */
 export interface UIBuilderClientHooks {
 	/**
-	 * Called before loading the page list. Return false to cancel loading.
+	 * Called before loading the page list. Throw an error to cancel loading.
 	 * @param context - Loader context with path, params, etc.
 	 */
-	beforeLoadPageList?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadPageList?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called after the page list is loaded.
 	 * @param context - Loader context
 	 */
 	afterLoadPageList?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called before loading the page builder. Return false to cancel loading.
+	 * Called before loading the page builder. Throw an error to cancel loading.
 	 * @param pageId - The page ID (undefined for new pages)
 	 * @param context - Loader context
 	 */
 	beforeLoadPageBuilder?: (
 		pageId: string | undefined,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after the page builder is loaded.
 	 * @param pageId - The page ID (undefined for new pages)

package/src/plugins/utils.ts

@@ -1,5 +1,96 @@
 import { createClient } from "better-call/client";
 
+/**
+ * Runs a hook with backward-compatible denial handling.
+ * Hooks may deny by returning a falsy value (old) or throwing (new).
+ * Both are normalized to an HTTP error via `createError` (`ctx.error`).
+ * Returns the hook's result so transform hooks can apply mutations.
+ *
+ * ## Migration note (v2.4 → v2.5)
+ *
+ * Old-style hooks signalled denial by returning `false` and allowance by returning `true`.
+ * Pre-shim call sites used `if (!result)` which treated `undefined` (fall-through) as deny.
+ * New-style hooks throw an Error to deny and return void/undefined to allow.
+ *
+ * The shim detects old-style boolean returns at runtime and emits a deprecation warning so
+ * that any hook with a code path returning a boolean is surfaced immediately. Hooks that fall
+ * through to `undefined` on **every** code path (no boolean return anywhere) cannot be
+ * distinguished from new-style void hooks — those hooks must be audited manually and updated
+ * to throw explicitly when they intend to deny access.
+ */
+export async function runHookWithShim<T>(
+	hookFn: () => Promise<T> | T,
+	createError: (
+		status: keyof typeof statusCodes | Status,
+		body: { message: string },
+	) => any,
+	defaultMessage: string,
+	errorStatus = 403 as keyof typeof statusCodes | Status,
+): Promise<Exclude<Awaited<T>, false>> {
+	let result: Awaited<T>;
+	try {
+		result = await hookFn();
+	} catch (e) {
+		throw createError(errorStatus, {
+			message: e instanceof Error ? e.message : defaultMessage,
+		});
+	}
+	// Detect old-style boolean returns (pre-v2.5 pattern).
+	// Emitting a warning here is the only reliable way to surface hooks that still rely on
+	// boolean returns — including hooks where one branch returns `false` and another falls
+	// through to `undefined`, which was previously denied by `if (!result)` at the call site
+	// but would now silently allow if the warning is not acted on.
+	if (typeof result === "boolean") {
+		if (process.env.NODE_ENV !== "production") {
+			console.warn(
+				`[btst] A lifecycle hook returned a boolean (${result}). ` +
+					`Boolean returns are deprecated — throw an Error to deny access instead. ` +
+					`IMPORTANT: any code path in this hook that falls through to undefined ` +
+					`now ALLOWS access (previously denied). ` +
+					`Update the hook to throw new Error("Unauthorized") to deny.`,
+			);
+		}
+		if (!result) {
+			throw createError(errorStatus, { message: defaultMessage });
+		}
+	}
+	return result as Exclude<Awaited<T>, false>;
+}
+
+/**
+ * Client-side equivalent of runHookWithShim — throws a plain Error instead of an HTTP error.
+ * Hooks may deny by returning false (old) or throwing (new); both normalize to an Error.
+ *
+ * See `runHookWithShim` for the full migration note on boolean-vs-void semantics.
+ */
+export async function runClientHookWithShim<T>(
+	hookFn: () => Promise<T> | T,
+	defaultMessage: string,
+): Promise<Exclude<Awaited<T>, false>> {
+	let result: Awaited<T>;
+	try {
+		result = await hookFn();
+	} catch (e) {
+		throw e instanceof Error ? e : new Error(defaultMessage);
+	}
+	// Detect old-style boolean returns and warn; see runHookWithShim for rationale.
+	if (typeof result === "boolean") {
+		if (process.env.NODE_ENV !== "production") {
+			console.warn(
+				`[btst] A lifecycle hook returned a boolean (${result}). ` +
+					`Boolean returns are deprecated — throw an Error to deny access instead. ` +
+					`IMPORTANT: any code path in this hook that falls through to undefined ` +
+					`now ALLOWS access (previously denied). ` +
+					`Update the hook to throw new Error("Unauthorized") to deny.`,
+			);
+		}
+		if (!result) {
+			throw new Error(defaultMessage);
+		}
+	}
+	return result as Exclude<Awaited<T>, false>;
+}
+
 /**
  * Returns true when a fetch error is a connection-refused / no-server error.
  * Used in SSR loaders to emit an actionable build-time warning when
@@ -18,7 +109,7 @@ export function isConnectionError(err: unknown): boolean {
 		code === "ERR_CONNECTION_REFUSED"
 	);
 }
-import type { Router, Endpoint } from "better-call";
+import type { Router, Endpoint, Status, statusCodes } from "better-call";
 
 interface CreateApiClientOptions {
 	baseURL?: string;