@btst/stack 2.3.0 → 2.4.0

package/src/plugins/ai-chat/client/context/page-ai-context.tsx

@@ -0,0 +1,240 @@
+"use client";
+
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useId,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+
+/**
+ * A client-side tool handler — receives the AI's tool call args and returns a result.
+ * The result is sent back to the model so it can continue the conversation.
+ */
+export type PageAIClientTool = (
+	args: any,
+) => Promise<{ success: boolean; message?: string }>;
+
+/**
+ * Configuration registered by a page to provide AI context and capabilities.
+ * Any component in the tree can call useRegisterPageAIContext with this config.
+ */
+export interface PageAIContextConfig {
+	/**
+	 * Identifier for the current route/page (e.g. "blog-post", "ui-builder-edit-page").
+	 * Shown as a badge in the chat header.
+	 */
+	routeName: string;
+
+	/**
+	 * Human-readable description of the current page and its content.
+	 * Injected into the AI system prompt so it understands what the user is looking at.
+	 * Capped at 8,000 characters server-side.
+	 */
+	pageDescription: string;
+
+	/**
+	 * Optional suggested prompts shown as quick-action chips in the chat empty state.
+	 * These augment (not replace) any static suggestions configured in plugin overrides.
+	 */
+	suggestions?: string[];
+
+	/**
+	 * Client-side tool handlers keyed by tool name.
+	 * When the AI calls a tool by this name, the handler is invoked with the tool args.
+	 * The result is sent back to the model via addToolResult.
+	 *
+	 * Tool schemas must be registered server-side via enablePageTools + clientToolSchemas
+	 * in aiChatBackendPlugin (built-in tools like fillBlogForm are pre-registered).
+	 */
+	clientTools?: Record<string, PageAIClientTool>;
+}
+
+interface PageAIAPIContextValue {
+	register: (id: string, config: PageAIContextConfig) => void;
+	unregister: (id: string) => void;
+	getActive: () => PageAIContextConfig | null;
+}
+
+/**
+ * Stable API context — holds register/unregister/getActive.
+ * Never changes reference, so useRegisterPageAIContext effects don't re-run
+ * simply because the provider re-rendered after a bumpVersion call.
+ */
+const PageAIAPIContext = createContext<PageAIAPIContextValue | null>(null);
+
+/**
+ * Reactive version context — incremented on every register/unregister.
+ * Consumers of usePageAIContext subscribe here so they re-render when
+ * registrations change and re-call getActive() to pick up the latest config.
+ */
+const PageAIVersionContext = createContext<number>(0);
+
+/**
+ * Provider that enables route-aware AI context across the app.
+ *
+ * Place this at the root layout — above all StackProviders — so it spans
+ * both your main app tree and any chat modals rendered as parallel/intercept routes.
+ *
+ * @example
+ * // app/layout.tsx
+ * import { PageAIContextProvider } from "@btst/stack/plugins/ai-chat/client/context"
+ *
+ * export default function RootLayout({ children }) {
+ *   return <PageAIContextProvider>{children}</PageAIContextProvider>
+ * }
+ */
+export function PageAIContextProvider({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	// Map from stable registration id → config
+	// Using useRef so mutations don't trigger re-renders of the provider itself
+	const registrationsRef = useRef<Map<string, PageAIContextConfig>>(new Map());
+	// Track insertion order so the last-registered (most specific) wins
+	const insertionOrderRef = useRef<string[]>([]);
+
+	// Version counter — bumped on every register/unregister so consumers re-read
+	const [version, setVersion] = useState(0);
+	const bumpVersion = useCallback(() => setVersion((v) => v + 1), []);
+
+	const register = useCallback(
+		(id: string, config: PageAIContextConfig) => {
+			registrationsRef.current.set(id, config);
+			// Move to end to mark as most recent
+			insertionOrderRef.current = insertionOrderRef.current.filter(
+				(k) => k !== id,
+			);
+			insertionOrderRef.current.push(id);
+			bumpVersion();
+		},
+		[bumpVersion],
+	);
+
+	const unregister = useCallback(
+		(id: string) => {
+			registrationsRef.current.delete(id);
+			insertionOrderRef.current = insertionOrderRef.current.filter(
+				(k) => k !== id,
+			);
+			bumpVersion();
+		},
+		[bumpVersion],
+	);
+
+	const getActive = useCallback((): PageAIContextConfig | null => {
+		const order = insertionOrderRef.current;
+		if (order.length === 0) return null;
+		// Last registered wins (most deeply nested / most recently mounted)
+		const lastId = order[order.length - 1];
+		if (!lastId) return null;
+		return registrationsRef.current.get(lastId) ?? null;
+	}, []);
+
+	// Memoize the API object so its reference never changes — this is what
+	// breaks the infinite loop: useRegisterPageAIContext has `ctx` (the API)
+	// in its effect deps, and a stable reference means the effect won't re-run
+	// just because the provider re-rendered after bumpVersion().
+	const api = useMemo(
+		() => ({ register, unregister, getActive }),
+		[register, unregister, getActive],
+	);
+
+	return (
+		<PageAIAPIContext.Provider value={api}>
+			<PageAIVersionContext.Provider value={version}>
+				{children}
+			</PageAIVersionContext.Provider>
+		</PageAIAPIContext.Provider>
+	);
+}
+
+/**
+ * Register page AI context from any component.
+ * The registration is cleaned up automatically when the component unmounts.
+ *
+ * Pass `null` to conditionally disable context (e.g. while data is loading).
+ *
+ * @example
+ * // Blog post page
+ * useRegisterPageAIContext(post ? {
+ *   routeName: "blog-post",
+ *   pageDescription: `Blog post: "${post.title}"\n\n${post.content?.slice(0, 16000)}`,
+ *   suggestions: ["Summarize this post", "What are the key takeaways?"],
+ * } : null)
+ */
+export function useRegisterPageAIContext(
+	config: PageAIContextConfig | null,
+): void {
+	// Use the stable API context — its reference never changes, so adding it
+	// to the dependency array below does NOT cause the effect to re-run after
+	// bumpVersion() fires. This breaks the register → bumpVersion → re-render
+	// → effect re-run → register loop that caused "Maximum update depth exceeded".
+	const ctx = useContext(PageAIAPIContext);
+	const id = useId();
+
+	// Always keep the ref current so clientTools handlers are never stale.
+	// Updating a ref during render is safe — the value is visible to any effect
+	// that runs in the same commit.
+	const configRef = useRef<PageAIContextConfig | null>(config);
+	configRef.current = config;
+
+	useEffect(() => {
+		if (!ctx || !configRef.current) return;
+		// Register a live proxy that always reads from configRef. This ensures
+		// clientTools handlers are fresh even when the effect doesn't re-run —
+		// for example when a handler's closure captures new state but the
+		// serializable fields (routeName, pageDescription, suggestions) are unchanged.
+		// JSON.stringify silently strips function values, so clientTools would be
+		// invisible to a plain JSON.stringify(config) dependency check.
+		ctx.register(id, {
+			get routeName() {
+				return configRef.current?.routeName ?? "";
+			},
+			get pageDescription() {
+				return configRef.current?.pageDescription ?? "";
+			},
+			get suggestions() {
+				return configRef.current?.suggestions;
+			},
+			get clientTools() {
+				return configRef.current?.clientTools;
+			},
+		});
+		return () => {
+			ctx.unregister(id);
+		};
+		// Track serializable fields individually. JSON.stringify on the whole config
+		// would silently strip clientTools (functions), making handler changes invisible.
+		// Handler freshness is provided by the ref-proxy above instead.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [
+		ctx,
+		id,
+		config === null,
+		config?.routeName,
+		config?.pageDescription,
+		JSON.stringify(config?.suggestions),
+	]);
+}
+
+/**
+ * Read the currently active page AI context.
+ * Returns null when no page has registered context, or when PageAIContextProvider
+ * is not in the tree.
+ *
+ * Used internally by ChatInterface to inject context into requests.
+ */
+export function usePageAIContext(): PageAIContextConfig | null {
+	// Subscribe to the version counter so this hook re-runs whenever a page
+	// registers or unregisters context, then read the latest active config.
+	useContext(PageAIVersionContext);
+	const ctx = useContext(PageAIAPIContext);
+	if (!ctx) return null;
+	return ctx.getActive();
+}

package/src/plugins/ai-chat/schemas.ts

@@ -37,4 +37,20 @@ export const chatRequestSchema = z.object({
 	),
 	conversationId: z.string().optional(),
 	model: z.string().optional(),
+	/**
+	 * Description of the current page context, injected into the AI system prompt.
+	 * Sent by ChatInterface when a page has registered context via useRegisterPageAIContext.
+	 */
+	pageContext: z.string().max(16000).optional(),
+	/**
+	 * Names of client-side tools currently available on the page.
+	 * The server includes matching tool schemas in the streamText call.
+	 */
+	availableTools: z.array(z.string()).optional(),
+	/**
+	 * The routeName registered by the page via useRegisterPageAIContext.
+	 * Cross-validated server-side against each built-in tool's route allowlist
+	 * to prevent a page from claiming tools intended for a different route.
+	 */
+	routeName: z.string().optional(),
 });

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/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,6 +30,7 @@ import {
 	serializeContentItem,
 	serializeContentItemWithType,
 } from "./getters";
+import { createCMSContentItem } from "./mutations";
 import type { QueryClient } from "@tanstack/react-query";
 import { CMS_QUERY_KEYS } from "./query-key-defs";
 
@@ -569,6 +570,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) => {

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

@@ -6,5 +6,11 @@ export {
 	type KanbanBackendHooks,
 } from "./plugin";
 export { getAllBoards, getBoardById, type BoardListResult } from "./getters";
+export {
+	createKanbanTask,
+	findOrCreateKanbanBoard,
+	getKanbanColumnsByBoardId,
+	type CreateKanbanTaskInput,
+} from "./mutations";
 export { serializeBoard, serializeColumn, serializeTask } from "./serializers";
 export { KANBAN_QUERY_KEYS } from "./query-key-defs";