@btst/stack 2.3.0 → 2.5.0

package/src/plugins/blog/client/components/pages/fill-blog-form-handler.ts

@@ -0,0 +1,38 @@
+import type { RefObject } from "react";
+import type { UseFormReturn } from "react-hook-form";
+
+/**
+ * Returns a `fillBlogForm` client tool handler bound to a form ref.
+ * Used by both the new-post and edit-post pages so the field-mapping
+ * logic stays in one place when the form schema changes.
+ */
+export function createFillBlogFormHandler(
+	formRef: RefObject<UseFormReturn<any> | null>,
+	successMessage: string,
+) {
+	return async ({
+		title,
+		content,
+		excerpt,
+		tags,
+	}: {
+		title?: string;
+		content?: string;
+		excerpt?: string;
+		tags?: string[];
+	}) => {
+		const form = formRef.current;
+		if (!form) return { success: false, message: "Form not ready" };
+		if (title !== undefined)
+			form.setValue("title", title, { shouldValidate: true });
+		if (content !== undefined)
+			form.setValue("content", content, { shouldValidate: true });
+		if (excerpt !== undefined) form.setValue("excerpt", excerpt);
+		if (tags !== undefined)
+			form.setValue(
+				"tags",
+				tags.map((name: string) => ({ name })),
+			);
+		return { success: true, message: successMessage };
+	};
+}

package/src/plugins/blog/client/components/pages/new-post-page.internal.tsx

@@ -7,6 +7,10 @@ import { PageWrapper } from "../shared/page-wrapper";
 import type { BlogPluginOverrides } from "../../overrides";
 import { BLOG_LOCALIZATION } from "../../localization";
 import { useRouteLifecycle } from "@workspace/ui/hooks/use-route-lifecycle";
+import { useRegisterPageAIContext } from "@btst/stack/plugins/ai-chat/client/context";
+import { useRef, useCallback } from "react";
+import type { UseFormReturn } from "react-hook-form";
+import { createFillBlogFormHandler } from "./fill-blog-form-handler";
 
 // Internal component with actual page content
 export function NewPostPage() {
@@ -35,6 +39,30 @@ export function NewPostPage() {
 		},
 	});
 
+	// Ref to capture the form instance from AddPostForm via onFormReady callback
+	const formRef = useRef<UseFormReturn<any> | null>(null);
+	const handleFormReady = useCallback((form: UseFormReturn<any>) => {
+		formRef.current = form;
+	}, []);
+
+	// Register AI context so the chat can fill in the new post form
+	useRegisterPageAIContext({
+		routeName: "blog-new-post",
+		pageDescription:
+			"User is creating a new blog post in the admin editor. IMPORTANT: When asked to write, draft, or create a blog post, you MUST call the fillBlogForm tool to populate the form fields directly — do NOT just output the text in your response.",
+		suggestions: [
+			"Write a post about AI trends",
+			"Draft an intro paragraph",
+			"Suggest 5 tags for this post",
+		],
+		clientTools: {
+			fillBlogForm: createFillBlogFormHandler(
+				formRef,
+				"Form filled successfully",
+			),
+		},
+	});
+
 	const handleClose = () => {
 		navigate(`${basePath}/blog`);
 	};
@@ -54,7 +82,11 @@ export function NewPostPage() {
 				title={localization.BLOG_POST_ADD_TITLE}
 				description={localization.BLOG_POST_ADD_DESCRIPTION}
 			/>
-			<AddPostForm onClose={handleClose} onSuccess={handleSuccess} />
+			<AddPostForm
+				onClose={handleClose}
+				onSuccess={handleSuccess}
+				onFormReady={handleFormReady}
+			/>
 		</PageWrapper>
 	);
 }

package/src/plugins/blog/client/components/pages/post-page.internal.tsx

@@ -20,6 +20,7 @@ import { Badge } from "@workspace/ui/components/badge";
 import { useRouteLifecycle } from "@workspace/ui/hooks/use-route-lifecycle";
 import { OnThisPage, OnThisPageSelect } from "../shared/on-this-page";
 import type { SerializedPost } from "../../../types";
+import { useRegisterPageAIContext } from "@btst/stack/plugins/ai-chat/client/context";
 
 // Internal component with actual page content
 export function PostPage({ slug }: { slug: string }) {
@@ -64,6 +65,25 @@ export function PostPage({ slug }: { slug: string }) {
 		enabled: !!post,
 	});
 
+	// Register page AI context so the chat can summarize and discuss this post
+	useRegisterPageAIContext(
+		post
+			? {
+					routeName: "blog-post",
+					pageDescription:
+						`Blog post: "${post.title}"\nAuthor: ${post.authorId ?? "Unknown"}\n\n${post.content ?? ""}`.slice(
+							0,
+							16000,
+						),
+					suggestions: [
+						"Summarize this post",
+						"What are the key takeaways?",
+						"Explain this in simpler terms",
+					],
+				}
+			: null,
+	);
+
 	if (!slug || !post) {
 		return (
 			<PageWrapper>

package/src/plugins/blog/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";
@@ -91,16 +92,16 @@ export interface BlogClientConfig {
  */
 export interface BlogClientHooks {
 	/**
-	 * Called before loading posts list. Return false to cancel loading.
+	 * Called before loading posts list. Throw an error to cancel loading.
 	 * @param filter - Filter parameters including published status
 	 * @param context - Loader context with path, params, etc.
 	 */
 	beforeLoadPosts?: (
 		filter: { published: boolean },
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called after posts are loaded. Return false to cancel further processing.
+	 * Called after posts are loaded. Throw an error to cancel further processing.
 	 * @param posts - Array of loaded posts or null
 	 * @param filter - Filter parameters used
 	 * @param context - Loader context
@@ -109,18 +110,18 @@ export interface BlogClientHooks {
 		posts: Post[] | null,
 		filter: { published: boolean },
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before loading a single post. Return false to cancel loading.
+	 * Called before loading a single post. Throw an error to cancel loading.
 	 * @param slug - Post slug being loaded
 	 * @param context - Loader context
 	 */
 	beforeLoadPost?: (
 		slug: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called after a post is loaded. Return false to cancel further processing.
+	 * Called after a post is loaded. Throw an error to cancel further processing.
 	 * @param post - Loaded post or null if not found
 	 * @param slug - Post slug that was requested
 	 * @param context - Loader context
@@ -129,17 +130,17 @@ export interface BlogClientHooks {
 		post: Post | null,
 		slug: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before loading the new post page. Return false to cancel.
+	 * Called before loading the new post page. Throw an error to cancel.
 	 * @param context - Loader context
 	 */
-	beforeLoadNewPost?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadNewPost?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called after the new post page is loaded. Return false to cancel.
+	 * Called after the new post page is loaded. Throw an error to cancel.
 	 * @param context - Loader context
 	 */
-	afterLoadNewPost?: (context: LoaderContext) => Promise<boolean> | boolean;
+	afterLoadNewPost?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called when a loading error occurs
 	 * @param error - The error that occurred
@@ -165,10 +166,10 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadPosts) {
-					const canLoad = await hooks.beforeLoadPosts({ published }, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPosts hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPosts!({ published }, context),
+						"Load prevented by beforeLoadPosts hook",
+					);
 				}
 
 				const limit = 10;
@@ -202,14 +203,10 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 				if (hooks?.afterLoadPosts) {
 					const posts =
 						queryClient.getQueryData<Post[]>(listQuery.queryKey) || null;
-					const canContinue = await hooks.afterLoadPosts(
-						posts,
-						{ published },
-						context,
+					await runClientHookWithShim(
+						() => hooks.afterLoadPosts!(posts, { published }, context),
+						"Load prevented by afterLoadPosts hook",
 					);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadPosts hook");
-					}
 				}
 
 				// Check if there was an error after afterLoadPosts hook
@@ -263,10 +260,10 @@ function createPostLoader(
 			try {
 				// Before hook
 				if (hooks?.beforeLoadPost) {
-					const canLoad = await hooks.beforeLoadPost(slug, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPost!(slug, context),
+						"Load prevented by beforeLoadPost hook",
+					);
 				}
 
 				const client = createApiClient<BlogApiRouter>({
@@ -285,10 +282,10 @@ function createPostLoader(
 				if (hooks?.afterLoadPost) {
 					const post =
 						queryClient.getQueryData<Post>(postQuery.queryKey) || null;
-					const canContinue = await hooks.afterLoadPost(post, slug, context);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.afterLoadPost!(post, slug, context),
+						"Load prevented by afterLoadPost hook",
+					);
 				}
 
 				// Check if there was an error after afterLoadPost hook
@@ -337,18 +334,18 @@ function createNewPostLoader(config: BlogClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadNewPost) {
-					const canLoad = await hooks.beforeLoadNewPost(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadNewPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadNewPost!(context),
+						"Load prevented by beforeLoadNewPost hook",
+					);
 				}
 
 				// After hook
 				if (hooks?.afterLoadNewPost) {
-					const canContinue = await hooks.afterLoadNewPost(context);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadNewPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.afterLoadNewPost!(context),
+						"Load prevented by afterLoadNewPost hook",
+					);
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR

package/src/plugins/client/index.ts

@@ -18,7 +18,11 @@ export type {
 	PluginOverrides,
 } from "../../types";
 
-export { createApiClient, isConnectionError } from "../utils";
+export {
+	createApiClient,
+	isConnectionError,
+	runClientHookWithShim,
+} from "../utils";
 
 // Re-export Yar types needed for plugins
 export type { Route } from "@btst/yar";

package/src/plugins/cms/api/index.ts

@@ -12,4 +12,8 @@ export {
 	serializeContentItem,
 	serializeContentItemWithType,
 } from "./getters";
+export {
+	createCMSContentItem,
+	type CreateCMSContentItemInput,
+} from "./mutations";
 export { CMS_QUERY_KEYS } from "./query-key-defs";

package/src/plugins/cms/api/mutations.ts

@@ -0,0 +1,84 @@
+import type { Adapter } from "@btst/db";
+import type { ContentType, ContentItem } from "../types";
+import { serializeContentItem } from "./getters";
+import type { SerializedContentItem } from "../types";
+
+/**
+ * Input for creating a new CMS content item.
+ */
+export interface CreateCMSContentItemInput {
+	/** URL-safe slug for the item */
+	slug: string;
+	/** Arbitrary data payload — should match the content type schema */
+	data: Record<string, unknown>;
+}
+
+/**
+ * Create a new content item for a content type (looked up by slug).
+ *
+ * Bypasses Zod schema validation and relation processing — the caller is
+ * responsible for providing valid, relation-free data. For relation fields or
+ * schema validation, use the HTTP endpoint instead.
+ *
+ * Throws if the content type is not found or the slug is already taken within
+ * that content type.
+ *
+ * @remarks **Security:** No authorization hooks (`onBeforeCreate`, `onAfterCreate`)
+ * are called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param contentTypeSlug - Slug of the target content type
+ * @param input - Item slug and data payload
+ */
+export async function createCMSContentItem(
+	adapter: Adapter,
+	contentTypeSlug: string,
+	input: CreateCMSContentItemInput,
+): Promise<SerializedContentItem> {
+	const contentType = await adapter.findOne<ContentType>({
+		model: "contentType",
+		where: [
+			{
+				field: "slug",
+				value: contentTypeSlug,
+				operator: "eq" as const,
+			},
+		],
+	});
+
+	if (!contentType) {
+		throw new Error(`Content type "${contentTypeSlug}" not found`);
+	}
+
+	const existing = await adapter.findOne<ContentItem>({
+		model: "contentItem",
+		where: [
+			{
+				field: "contentTypeId",
+				value: contentType.id,
+				operator: "eq" as const,
+			},
+			{ field: "slug", value: input.slug, operator: "eq" as const },
+		],
+	});
+
+	if (existing) {
+		throw new Error(
+			`Content item with slug "${input.slug}" already exists in type "${contentTypeSlug}"`,
+		);
+	}
+
+	const item = await adapter.create<ContentItem>({
+		model: "contentItem",
+		data: {
+			contentTypeId: contentType.id,
+			slug: input.slug,
+			data: JSON.stringify(input.data),
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+
+	return serializeContentItem(item);
+}

package/src/plugins/cms/api/plugin.ts

@@ -30,8 +30,10 @@ import {
 	serializeContentItem,
 	serializeContentItemWithType,
 } from "./getters";
+import { createCMSContentItem } from "./mutations";
 import type { QueryClient } from "@tanstack/react-query";
 import { CMS_QUERY_KEYS } from "./query-key-defs";
+import { runHookWithShim } from "../../utils";
 
 /**
  * Route keys for the CMS plugin — matches the keys returned by
@@ -569,6 +571,14 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 				return getContentItemById(adapter, id);
 			},
 			prefetchForRoute: createCMSPrefetchForRoute(adapter),
+			// Mutations
+			createContentItem: async (
+				typeSlug: string,
+				input: Parameters<typeof createCMSContentItem>[2],
+			) => {
+				await ensureSynced(adapter);
+				return createCMSContentItem(adapter, typeSlug, input);
+			},
 		}),
 
 		routes: (adapter: Adapter) => {
@@ -770,13 +780,11 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					// Call before hook - may deny operation
 					const processedData = validation.data as Record<string, unknown>;
 					if (config.hooks?.onBeforeCreate) {
-						const result = await config.hooks.onBeforeCreate(
-							processedData,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeCreate!(processedData, context),
+							ctx.error,
+							"Create operation denied",
 						);
-						if (result === false) {
-							throw ctx.error(403, { message: "Create operation denied" });
-						}
 					}
 
 					const item = await adapter.create<ContentItem>({
@@ -913,14 +921,11 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					// Call before hook - may deny operation
 					const processedData = validatedData;
 					if (config.hooks?.onBeforeUpdate && validatedData) {
-						const result = await config.hooks.onBeforeUpdate(
-							id,
-							validatedData,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeUpdate!(id, validatedData, context),
+							ctx.error,
+							"Update operation denied",
 						);
-						if (result === false) {
-							throw ctx.error(403, { message: "Update operation denied" });
-						}
 					}
 
 					// Sync relations to junction table if data was updated
@@ -987,10 +992,11 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 
 					// Call before hook
 					if (config.hooks?.onBeforeDelete) {
-						const canDelete = await config.hooks.onBeforeDelete(id, context);
-						if (!canDelete) {
-							throw ctx.error(403, { message: "Delete operation denied" });
-						}
+						await runHookWithShim(
+							() => config.hooks!.onBeforeDelete!(id, context),
+							ctx.error,
+							"Delete operation denied",
+						);
 					}
 
 					await adapter.delete({

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

@@ -3,6 +3,7 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -52,24 +53,24 @@ export interface LoaderContext {
  */
 export interface CMSClientHooks {
 	/**
-	 * Called before loading the dashboard page. Return false to cancel loading.
+	 * Called before loading the dashboard page. Throw an error to cancel loading.
 	 * @param context - Loader context with path, params, etc.
 	 */
-	beforeLoadDashboard?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadDashboard?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called after the dashboard is loaded.
 	 * @param context - Loader context
 	 */
 	afterLoadDashboard?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called before loading a content list page. Return false to cancel loading.
+	 * Called before loading a content list page. Throw an error to cancel loading.
 	 * @param typeSlug - The content type slug
 	 * @param context - Loader context
 	 */
 	beforeLoadContentList?: (
 		typeSlug: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after a content list is loaded.
 	 * @param typeSlug - The content type slug
@@ -80,7 +81,7 @@ export interface CMSClientHooks {
 		context: LoaderContext,
 	) => Promise<void> | void;
 	/**
-	 * Called before loading the content editor page. Return false to cancel loading.
+	 * Called before loading the content editor page. Throw an error to cancel loading.
 	 * @param typeSlug - The content type slug
 	 * @param id - The content item ID (undefined for new items)
 	 * @param context - Loader context
@@ -89,7 +90,7 @@ export interface CMSClientHooks {
 		typeSlug: string,
 		id: string | undefined,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after the content editor is loaded.
 	 * @param typeSlug - The content type slug
@@ -149,10 +150,10 @@ function createDashboardLoader(config: CMSClientConfig) {
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadDashboard) {
-					const canLoad = await hooks.beforeLoadDashboard(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadDashboard hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadDashboard!(context),
+						"Load prevented by beforeLoadDashboard hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -217,10 +218,10 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadContentList) {
-					const canLoad = await hooks.beforeLoadContentList(typeSlug, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadContentList hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadContentList!(typeSlug, context),
+						"Load prevented by beforeLoadContentList hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -321,14 +322,10 @@ function createContentEditorLoader(
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadContentEditor) {
-					const canLoad = await hooks.beforeLoadContentEditor(
-						typeSlug,
-						id,
-						context,
+					await runClientHookWithShim(
+						() => hooks.beforeLoadContentEditor!(typeSlug, id, context),
+						"Load prevented by beforeLoadContentEditor hook",
 					);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadContentEditor hook");
-					}
 				}
 
 				const client = createApiClient<CMSApiRouter>({

package/src/plugins/cms/types.ts

@@ -248,16 +248,16 @@ export interface CMSHookContext {
 /**
  * Hooks for customizing CMS backend behavior
  *
- * Note: Before hooks can only deny operations by returning `false`.
+ * Note: Before hooks deny operations by throwing an error.
  * They cannot modify the data being saved. This ensures consistency
  * between the stored content item data and relation junction tables.
  */
 export interface CMSBackendHooks {
-	/** Called before creating a content item. Return false to deny the operation. */
+	/** Called before creating a content item. Throw an error to deny the operation. */
 	onBeforeCreate?: (
 		data: Record<string, unknown>,
 		context: CMSHookContext,
-	) => Promise<false | void> | false | void;
+	) => Promise<void> | void;
 
 	/** Called after creating a content item */
 	onAfterCreate?: (
@@ -265,12 +265,12 @@ export interface CMSBackendHooks {
 		context: CMSHookContext,
 	) => Promise<void> | void;
 
-	/** Called before updating a content item. Return false to deny the operation. */
+	/** Called before updating a content item. Throw an error to deny the operation. */
 	onBeforeUpdate?: (
 		id: string,
 		data: Record<string, unknown>,
 		context: CMSHookContext,
-	) => Promise<false | void> | false | void;
+	) => Promise<void> | void;
 
 	/** Called after updating a content item */
 	onAfterUpdate?: (
@@ -278,11 +278,11 @@ export interface CMSBackendHooks {
 		context: CMSHookContext,
 	) => Promise<void> | void;
 
-	/** Called before deleting a content item */
+	/** Called before deleting a content item. Throw an error to deny the operation. */
 	onBeforeDelete?: (
 		id: string,
 		context: CMSHookContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/** Called after deleting a content item */
 	onAfterDelete?: (id: string, context: CMSHookContext) => Promise<void> | void;