@btst/stack 2.2.0 → 2.4.0

package/src/plugins/blog/api/serializers.ts

@@ -0,0 +1,27 @@
+import type { Post, Tag, SerializedPost, SerializedTag } from "../types";
+
+/**
+ * Serialize a Tag for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeTag(tag: Tag): SerializedTag {
+	return {
+		...tag,
+		createdAt: tag.createdAt.toISOString(),
+		updatedAt: tag.updatedAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a Post (with tags) for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializePost(post: Post & { tags: Tag[] }): SerializedPost {
+	return {
+		...post,
+		createdAt: post.createdAt.toISOString(),
+		updatedAt: post.updatedAt.toISOString(),
+		publishedAt: post.publishedAt?.toISOString(),
+		tags: post.tags.map(serializeTag),
+	};
+}

package/src/plugins/blog/client/components/forms/post-forms.tsx

@@ -40,7 +40,7 @@ import {
 
 import { zodResolver } from "@hookform/resolvers/zod";
 import { Loader2 } from "lucide-react";
-import { lazy, memo, Suspense, useMemo, useState } from "react";
+import { lazy, memo, Suspense, useEffect, useMemo, useState } from "react";
 import {
 	type FieldPath,
 	type SubmitHandler,
@@ -325,6 +325,10 @@ const CustomPostUpdateSchema = PostUpdateSchema.omit({
 type AddPostFormProps = {
 	onClose: () => void;
 	onSuccess: (post: { published: boolean }) => void;
+	/** Called once with the form instance so parent components can access form state */
+	onFormReady?: (
+		form: UseFormReturn<z.input<typeof CustomPostCreateSchema>>,
+	) => void;
 };
 
 const addPostFormPropsAreEqual = (
@@ -333,10 +337,15 @@ const addPostFormPropsAreEqual = (
 ): boolean => {
 	if (prevProps.onClose !== nextProps.onClose) return false;
 	if (prevProps.onSuccess !== nextProps.onSuccess) return false;
+	if (prevProps.onFormReady !== nextProps.onFormReady) return false;
 	return true;
 };
 
-const AddPostFormComponent = ({ onClose, onSuccess }: AddPostFormProps) => {
+const AddPostFormComponent = ({
+	onClose,
+	onSuccess,
+	onFormReady,
+}: AddPostFormProps) => {
 	const [featuredImageUploading, setFeaturedImageUploading] = useState(false);
 	const { localization } = usePluginOverrides<
 		BlogPluginOverrides,
@@ -393,6 +402,12 @@ const AddPostFormComponent = ({ onClose, onSuccess }: AddPostFormProps) => {
 		},
 	});
 
+	// Expose form instance to parent for AI context integration
+	useEffect(() => {
+		onFormReady?.(form);
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, []);
+
 	return (
 		<PostFormBody
 			form={form}
@@ -417,6 +432,10 @@ type EditPostFormProps = {
 	onClose: () => void;
 	onSuccess: (post: { slug: string; published: boolean }) => void;
 	onDelete?: () => void;
+	/** Called once with the form instance so parent components can access form state */
+	onFormReady?: (
+		form: UseFormReturn<z.input<typeof CustomPostUpdateSchema>>,
+	) => void;
 };
 
 const editPostFormPropsAreEqual = (
@@ -427,6 +446,7 @@ const editPostFormPropsAreEqual = (
 	if (prevProps.onClose !== nextProps.onClose) return false;
 	if (prevProps.onSuccess !== nextProps.onSuccess) return false;
 	if (prevProps.onDelete !== nextProps.onDelete) return false;
+	if (prevProps.onFormReady !== nextProps.onFormReady) return false;
 	return true;
 };
 
@@ -435,6 +455,7 @@ const EditPostFormComponent = ({
 	onClose,
 	onSuccess,
 	onDelete,
+	onFormReady,
 }: EditPostFormProps) => {
 	const [featuredImageUploading, setFeaturedImageUploading] = useState(false);
 	const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
@@ -537,6 +558,12 @@ const EditPostFormComponent = ({
 		values: initialData as z.input<typeof schema>,
 	});
 
+	// Expose form instance to parent for AI context integration
+	useEffect(() => {
+		onFormReady?.(form);
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, []);
+
 	if (!post) {
 		return <EmptyList message={localization.BLOG_PAGE_NOT_FOUND_DESCRIPTION} />;
 	}

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

@@ -7,6 +7,10 @@ import { PageWrapper } from "../shared/page-wrapper";
 import { BLOG_LOCALIZATION } from "../../localization";
 import type { BlogPluginOverrides } from "../../overrides";
 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 EditPostPage({ slug }: { slug: string }) {
@@ -36,6 +40,29 @@ export function EditPostPage({ slug }: { slug: string }) {
 		},
 	});
 
+	// Ref to capture the form instance from EditPostForm 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 edit form
+	useRegisterPageAIContext({
+		routeName: "blog-edit-post",
+		pageDescription: `User is editing a blog post (slug: "${slug}") in the admin editor.`,
+		suggestions: [
+			"Improve this post's title",
+			"Rewrite the intro paragraph",
+			"Suggest better tags",
+		],
+		clientTools: {
+			fillBlogForm: createFillBlogFormHandler(
+				formRef,
+				"Form updated successfully",
+			),
+		},
+	});
+
 	const handleClose = () => {
 		navigate(`${basePath}/blog`);
 	};
@@ -61,6 +88,7 @@ export function EditPostPage({ slug }: { slug: string }) {
 				onClose={handleClose}
 				onSuccess={handleSuccess}
 				onDelete={handleDelete}
+				onFormReady={handleFormReady}
 			/>
 		</PageWrapper>
 	);

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

@@ -1,6 +1,7 @@
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -226,6 +227,12 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -299,6 +306,12 @@ function createPostLoader(
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -398,6 +411,12 @@ function createTagLoader(tagSlug: string, config: BlogClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}

package/src/plugins/blog/query-keys.ts

@@ -5,6 +5,7 @@ import {
 import type { BlogApiRouter } from "./api";
 import { createApiClient } from "@btst/stack/plugins/client";
 import type { SerializedPost, SerializedTag } from "./types";
+import { postsListDiscriminator } from "./api/query-key-defs";
 
 interface PostsListParams {
 	query?: string;
@@ -71,15 +72,12 @@ function createPostsQueries(
 	return createQueryKeys("posts", {
 		list: (params?: PostsListParams) => ({
 			queryKey: [
-				{
-					query:
-						params?.query !== undefined && params?.query?.trim() === ""
-							? undefined
-							: params?.query,
-					limit: params?.limit ?? 10,
+				postsListDiscriminator({
 					published: params?.published ?? true,
+					limit: params?.limit ?? 10,
 					tagSlug: params?.tagSlug,
-				},
+					query: params?.query,
+				}),
 			],
 			queryFn: async ({ pageParam }: { pageParam?: number }) => {
 				try {

package/src/plugins/client/index.ts

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

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

@@ -191,6 +191,30 @@ export async function getAllContentItems(
 	};
 }
 
+/**
+ * Retrieve a single content item by its ID.
+ * Returns null if the item is not found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param id - The content item ID (UUID)
+ */
+export async function getContentItemById(
+	adapter: Adapter,
+	id: string,
+): Promise<SerializedContentItemWithType | null> {
+	const item = await adapter.findOne<ContentItemWithType>({
+		model: "contentItem",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+		join: { contentType: true },
+	});
+	if (!item) return null;
+	return serializeContentItemWithType(item);
+}
+
 /**
  * Retrieve a single content item by its slug within a content type.
  * Returns null if the content type or item is not found.

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

@@ -1,6 +1,19 @@
-export { cmsBackendPlugin, type CMSApiRouter } from "./plugin";
+export {
+	cmsBackendPlugin,
+	type CMSApiRouter,
+	type CMSRouteKey,
+} from "./plugin";
 export {
 	getAllContentTypes,
 	getAllContentItems,
 	getContentItemBySlug,
+	getContentItemById,
+	serializeContentType,
+	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

@@ -25,10 +25,38 @@ import {
 	getAllContentTypes,
 	getAllContentItems,
 	getContentItemBySlug,
+	getContentItemById,
 	serializeContentType,
 	serializeContentItem,
 	serializeContentItemWithType,
 } from "./getters";
+import { createCMSContentItem } from "./mutations";
+import type { QueryClient } from "@tanstack/react-query";
+import { CMS_QUERY_KEYS } from "./query-key-defs";
+
+/**
+ * Route keys for the CMS plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type CMSRouteKey =
+	| "dashboard"
+	| "contentList"
+	| "newContent"
+	| "editContent";
+
+interface CMSPrefetchForRoute {
+	(key: "dashboard" | "newContent", qc: QueryClient): Promise<void>;
+	(
+		key: "contentList",
+		qc: QueryClient,
+		params: { typeSlug: string },
+	): Promise<void>;
+	(
+		key: "editContent",
+		qc: QueryClient,
+		params: { typeSlug: string; id: string },
+	): Promise<void>;
+}
 
 /**
  * Sync content types from config to database
@@ -443,6 +471,79 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 		return syncPromise;
 	};
 
+	const getContentTypesWithCounts = async (adapter: Adapter) => {
+		const contentTypes = await getAllContentTypes(adapter);
+		return Promise.all(
+			contentTypes.map(async (ct) => {
+				const count: number = await adapter.count({
+					model: "contentItem",
+					where: [
+						{ field: "contentTypeId", value: ct.id, operator: "eq" as const },
+					],
+				});
+				return { ...ct, itemCount: count };
+			}),
+		);
+	};
+
+	const createCMSPrefetchForRoute = (adapter: Adapter): CMSPrefetchForRoute => {
+		return async function prefetchForRoute(
+			key: CMSRouteKey,
+			qc: QueryClient,
+			params?: Record<string, string>,
+		): Promise<void> {
+			// Sync content types once at the top — idempotent for concurrent SSG calls
+			await ensureSynced(adapter);
+
+			switch (key) {
+				case "dashboard":
+				case "newContent": {
+					const typesWithCounts = await getContentTypesWithCounts(adapter);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), typesWithCounts);
+					break;
+				}
+				case "contentList": {
+					const typeSlug = params?.typeSlug ?? "";
+					const [contentTypes, contentItems] = await Promise.all([
+						getContentTypesWithCounts(adapter),
+						getAllContentItems(adapter, typeSlug, { limit: 20, offset: 0 }),
+					]);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
+					qc.setQueryData(
+						CMS_QUERY_KEYS.contentList({ typeSlug, limit: 20, offset: 0 }),
+						{
+							pages: [
+								{
+									items: contentItems.items,
+									total: contentItems.total,
+									limit: contentItems.limit ?? 20,
+									offset: contentItems.offset ?? 0,
+								},
+							],
+							pageParams: [0],
+						},
+					);
+					break;
+				}
+				case "editContent": {
+					const typeSlug = params?.typeSlug ?? "";
+					const id = params?.id ?? "";
+					const [contentTypes, item] = await Promise.all([
+						getContentTypesWithCounts(adapter),
+						id ? getContentItemById(adapter, id) : Promise.resolve(null),
+					]);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
+					if (id) {
+						qc.setQueryData(CMS_QUERY_KEYS.contentDetail(typeSlug, id), item);
+					}
+					break;
+				}
+				default:
+					break;
+			}
+		} as CMSPrefetchForRoute;
+	};
+
 	return defineBackendPlugin({
 		name: "cms",
 
@@ -464,6 +565,19 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 				await ensureSynced(adapter);
 				return getContentItemBySlug(adapter, contentTypeSlug, slug);
 			},
+			getContentItemById: async (id: string) => {
+				await ensureSynced(adapter);
+				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) => {