@btst/stack 3.0.0-rc.2 → 3.0.0-rc.3

package/src/plugins/blog/__tests__/client-sweep.test.tsx

@@ -7,16 +7,24 @@ import { Form, FormField } from "@workspace/ui/components/form";
 // Core primitives MUST be imported from the package entry (not relative src
 // paths) so they share module identity — and React context — with the blog
 // components, which resolve `@btst/stack/*` via package self-reference.
-import {
-	StackProvider,
-	type StackAuthProvider,
-	type StackI18nProvider,
-} from "@btst/stack/context";
+import { StackProvider, type StackI18nProvider } from "@btst/stack/context";
+import { defineAuthorization } from "@btst/stack/authorization";
+import { createClientAuth } from "@btst/stack/authorization/client";
+import { ComposedRoute } from "@btst/stack/client/components";
 import { FeaturedImageField } from "../client/components/forms/image-field";
-import { EditPostForm } from "../client/components/forms/post-forms";
+import {
+	AddPostForm,
+	EditPostForm,
+} from "../client/components/forms/post-forms";
 import { PostsList } from "../client/components/shared/posts-list";
 import { SearchInput } from "../client/components/shared/search-input";
+import { DefaultError } from "../client/components/shared/default-error";
 import type { SerializedPost } from "../types";
+import { blogPermissions } from "../permissions";
+import { z } from "zod";
+import { createIdentityTestAuth } from "../../../__tests__/auth-test-utils";
+import { createTestClientStack } from "../../../__tests__/client-stack-test-utils";
+import { blogClientPlugin } from "../client/plugin";
 
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -33,6 +41,7 @@ const hooks = vi.hoisted(() => ({
 	useDeletePost: vi.fn(),
 	usePostForm: vi.fn(),
 	usePostSearch: vi.fn(),
+	useSuspensePosts: vi.fn(),
 	useTags: vi.fn(),
 }));
 
@@ -88,6 +97,12 @@ beforeEach(() => {
 		},
 	});
 	hooks.usePostSearch.mockReturnValue({ data: [], isLoading: false });
+	hooks.useSuspensePosts.mockReturnValue({
+		posts: [],
+		loadMore: vi.fn(),
+		hasMore: false,
+		isLoadingMore: false,
+	});
 	hooks.useTags.mockReturnValue({ tags: [], isLoading: false, error: null });
 });
 
@@ -106,6 +121,14 @@ async function render(ui: React.ReactElement) {
 	});
 }
 
+function createBlogStack() {
+	return createTestClientStack({ blog: blogClientPlugin() });
+}
+
+function blogOverrides() {
+	return { uploadImage: async () => "" };
+}
+
 function texts(): string {
 	return container.textContent ?? "";
 }
@@ -151,7 +174,7 @@ describe("FeaturedImageField notifications (useNotify)", () => {
 
 		await render(
 			<StackProvider
-				basePath="/pages"
+				stack={createBlogStack()}
 				notify={notify}
 				overrides={{ blog: { uploadImage } }}
 			>
@@ -173,7 +196,7 @@ describe("FeaturedImageField notifications (useNotify)", () => {
 
 		await render(
 			<StackProvider
-				basePath="/pages"
+				stack={createBlogStack()}
 				notify={notify}
 				overrides={{ blog: { uploadImage } }}
 			>
@@ -194,7 +217,7 @@ describe("FeaturedImageField notifications (useNotify)", () => {
 
 		await render(
 			<StackProvider
-				basePath="/pages"
+				stack={createBlogStack()}
 				notify={notify}
 				overrides={{ blog: { uploadImage } }}
 			>
@@ -209,10 +232,139 @@ describe("FeaturedImageField notifications (useNotify)", () => {
 	});
 });
 
-describe("EditPostForm delete control (CanAccess)", () => {
+describe("Blog route authorization errors", () => {
+	it("redirects an anonymous user when a protected route query returns 401", async () => {
+		const navigate = vi.fn();
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		const error = Object.assign(new Error("Authentication required"), {
+			statusCode: 401,
+		});
+		const ProtectedQueryPage = () => {
+			throw error;
+		};
+
+		await render(
+			<StackProvider
+				stack={createBlogStack()}
+				router={{ navigate }}
+				overrides={{ blog: blogOverrides() }}
+				auth={createIdentityTestAuth(() => null, { loginPath: "/login" })}
+				initialIdentity={null}
+			>
+				<ComposedRoute
+					path="/blog/example/edit"
+					PageComponent={ProtectedQueryPage}
+					ErrorComponent={DefaultError}
+					LoadingComponent={() => null}
+					onError={() => {}}
+				/>
+			</StackProvider>,
+		);
+
+		expect(navigate).toHaveBeenCalledWith("/login");
+		expect(texts()).not.toContain("Something went wrong");
+	});
+
+	it("treats a route-data 401 as authoritative over a stale client identity", async () => {
+		const navigate = vi.fn();
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		const ProtectedQueryPage = () => {
+			throw Object.assign(new Error("Session expired"), { statusCode: 401 });
+		};
+
+		await render(
+			<StackProvider
+				stack={createBlogStack()}
+				router={{ navigate }}
+				overrides={{ blog: blogOverrides() }}
+				auth={createIdentityTestAuth(
+					() => ({ id: "stale-user", role: "user" }),
+					{ loginPath: "/login" },
+				)}
+				initialIdentity={{ id: "stale-user", role: "user" }}
+			>
+				<ComposedRoute
+					path="/blog/example/edit"
+					PageComponent={ProtectedQueryPage}
+					ErrorComponent={DefaultError}
+					LoadingComponent={() => null}
+					onError={() => {}}
+				/>
+			</StackProvider>,
+		);
+
+		expect(navigate).toHaveBeenCalledWith("/login");
+		expect(texts()).not.toContain("Something went wrong");
+	});
+
+	it("redirects an authoritative route-data 401 while client identity is pending", async () => {
+		const navigate = vi.fn();
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		const ProtectedQueryPage = () => {
+			throw Object.assign(new Error("Authentication required"), {
+				statusCode: 401,
+			});
+		};
+
+		await render(
+			<StackProvider
+				stack={createBlogStack()}
+				router={{ navigate }}
+				overrides={{ blog: blogOverrides() }}
+				auth={createIdentityTestAuth(() => new Promise<null>(() => {}), {
+					loginPath: "/login",
+				})}
+			>
+				<ComposedRoute
+					path="/blog/example/edit"
+					PageComponent={ProtectedQueryPage}
+					ErrorComponent={DefaultError}
+					LoadingComponent={() => null}
+					onError={() => {}}
+				/>
+			</StackProvider>,
+		);
+
+		expect(navigate).toHaveBeenCalledWith("/login");
+		expect(texts()).not.toContain("Something went wrong");
+	});
+});
+
+describe("EditPostForm operation descriptor controls", () => {
+	it("separates draft creation from create-and-publish presentation", async () => {
+		const authorization = defineAuthorization({
+			identity: z.object({ id: z.string(), role: z.literal("user") }),
+			permissions: [blogPermissions] as const,
+			rules: ({ blog }) => [
+				blog.post.create.when(({ facts }) => facts.publish === "draft"),
+			],
+		});
+		const auth = createClientAuth({
+			authorization,
+			getIdentity: () => ({ id: "user-1", role: "user" as const }),
+		});
+
+		await render(
+			<StackProvider
+				stack={createBlogStack()}
+				overrides={{ blog: blogOverrides() }}
+				auth={auth}
+				initialIdentity={{ id: "user-1", role: "user" }}
+			>
+				<AddPostForm onClose={() => {}} onSuccess={() => {}} />
+			</StackProvider>,
+		);
+
+		expect(texts()).toContain("Create Post");
+		expect(texts()).not.toContain("Published");
+	});
+
 	it("shows the delete button without an auth provider", async () => {
 		await render(
-			<StackProvider basePath="/pages" overrides={{ blog: {} }}>
+			<StackProvider
+				stack={createBlogStack()}
+				overrides={{ blog: blogOverrides() }}
+			>
 				<EditPostForm
 					postSlug="hello-world"
 					onClose={() => {}}
@@ -223,19 +375,27 @@ describe("EditPostForm delete control (CanAccess)", () => {
 
 		expect(texts()).toContain("Delete Post");
 	});
-
-	it("hides the delete button when can() denies blog:post/delete", async () => {
-		const can = vi.fn(
-			({ resource, action }: { resource: string; action: string }) =>
-				!(resource === "blog:post" && action === "delete"),
-		);
-		const auth: StackAuthProvider = {
-			getIdentity: () => ({ id: "user-1" }),
-			can,
-		};
+	it("uses the Blog update and delete descriptors with one-rule client authorization", async () => {
+		const authorization = defineAuthorization({
+			identity: z.object({ id: z.string(), role: z.literal("user") }),
+			permissions: [blogPermissions] as const,
+			rules: ({ blog }) => [
+				blog.post.update.when(() => false),
+				blog.post.delete.when(() => false),
+			],
+		});
+		const auth = createClientAuth({
+			authorization,
+			getIdentity: () => ({ id: "user-1", role: "user" as const }),
+		});
 
 		await render(
-			<StackProvider basePath="/pages" overrides={{ blog: {} }} auth={auth}>
+			<StackProvider
+				stack={createBlogStack()}
+				overrides={{ blog: blogOverrides() }}
+				auth={auth}
+				initialIdentity={{ id: "user-1", role: "user" }}
+			>
 				<EditPostForm
 					postSlug="hello-world"
 					onClose={() => {}}
@@ -244,16 +404,9 @@ describe("EditPostForm delete control (CanAccess)", () => {
 			</StackProvider>,
 		);
 
-		// The rest of the form still renders; only the delete control is gone.
 		expect(texts()).toContain("Update Post");
+		expect(texts()).not.toContain("Published");
 		expect(texts()).not.toContain("Delete Post");
-		expect(can).toHaveBeenCalledWith(
-			expect.objectContaining({
-				resource: "blog:post",
-				action: "delete",
-				params: { id: post.id },
-			}),
-		);
 	});
 });
 
@@ -276,7 +429,11 @@ describe("SearchInput list state (useListState)", () => {
 		const router = createMockRouter("q=hello");
 
 		await render(
-			<StackProvider basePath="/pages" router={router} overrides={{ blog: {} }}>
+			<StackProvider
+				stack={createBlogStack()}
+				router={router}
+				overrides={{ blog: blogOverrides() }}
+			>
 				<SearchInput />
 			</StackProvider>,
 		);
@@ -292,7 +449,11 @@ describe("SearchInput list state (useListState)", () => {
 		const router = createMockRouter();
 
 		await render(
-			<StackProvider basePath="/pages" router={router} overrides={{ blog: {} }}>
+			<StackProvider
+				stack={createBlogStack()}
+				router={router}
+				overrides={{ blog: blogOverrides() }}
+			>
 				<SearchInput />
 			</StackProvider>,
 		);
@@ -338,7 +499,11 @@ describe("SearchInput list state (useListState)", () => {
 		const router = createMockRouter("q=hello");
 
 		await render(
-			<StackProvider basePath="/pages" router={router} overrides={{ blog: {} }}>
+			<StackProvider
+				stack={createBlogStack()}
+				router={router}
+				overrides={{ blog: blogOverrides() }}
+			>
 				<SearchInput />
 			</StackProvider>,
 		);
@@ -369,7 +534,10 @@ describe("SearchInput list state (useListState)", () => {
 describe("blog i18n precedence (useTranslate + overrides.localization)", () => {
 	it("renders the English default without providers", async () => {
 		await render(
-			<StackProvider basePath="/pages" overrides={{ blog: {} }}>
+			<StackProvider
+				stack={createBlogStack()}
+				overrides={{ blog: blogOverrides() }}
+			>
 				<PostsList posts={[]} />
 			</StackProvider>,
 		);
@@ -384,7 +552,11 @@ describe("blog i18n precedence (useTranslate + overrides.localization)", () => {
 		};
 
 		await render(
-			<StackProvider basePath="/pages" overrides={{ blog: {} }} i18n={i18n}>
+			<StackProvider
+				stack={createBlogStack()}
+				overrides={{ blog: blogOverrides() }}
+				i18n={i18n}
+			>
 				<PostsList posts={[]} />
 			</StackProvider>,
 		);
@@ -399,9 +571,12 @@ describe("blog i18n precedence (useTranslate + overrides.localization)", () => {
 
 		await render(
 			<StackProvider
-				basePath="/pages"
+				stack={createBlogStack()}
 				overrides={{
-					blog: { localization: { BLOG_LIST_EMPTY: "Custom empty state" } },
+					blog: {
+						...blogOverrides(),
+						localization: { BLOG_LIST_EMPTY: "Custom empty state" },
+					},
 				}}
 				i18n={{ translate }}
 			>

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

@@ -28,7 +28,7 @@ export interface PostListResult {
  * Retrieve all posts matching optional filter criteria.
  * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
  *
- * @remarks **Security:** Authorization hooks (e.g. `onBeforeListPosts`) are NOT
+ * @remarks **Security:** Operation authorization and lifecycle hooks are NOT
  * called. The caller is responsible for any access-control checks before
  * invoking this function.
  *
@@ -187,7 +187,7 @@ export async function getAllPosts(
  * Returns null if no post is 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
+ * @remarks **Security:** Operation authorization and lifecycle hooks are NOT called. The caller is
  * responsible for any access-control checks before invoking this function.
  *
  * @param adapter - The database adapter
@@ -230,7 +230,7 @@ export async function getPostBySlug(
  * Retrieve all tags, sorted alphabetically by name.
  * 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
+ * @remarks **Security:** Operation authorization and lifecycle hooks are NOT called. The caller is
  * responsible for any access-control checks before invoking this function.
  *
  * @param adapter - The database adapter

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

@@ -12,7 +12,9 @@ export {
 	deletePost,
 	type CreatePostInput,
 	type UpdatePostInput,
+	type UpdatePostOptions,
 } from "./mutations";
 export { serializePost, serializeTag } from "./serializers";
 export { BLOG_QUERY_KEYS } from "./query-key-defs";
 export { createBlogQueryKeys } from "../query-keys";
+export { blogPermissions } from "../permissions";

package/src/plugins/blog/api/lifecycle-migrations.ts

@@ -0,0 +1,19 @@
+/**
+ * Removed Blog lifecycle names and their canonical v3 replacements.
+ *
+ * This structured inventory is the source for migration documentation and
+ * repository guards. Names absent from this map did not change.
+ */
+export const BLOG_LIFECYCLE_HOOK_MIGRATIONS = Object.freeze({
+	onBeforeNextPreviousPosts: "onBeforeGetNextPreviousPosts",
+	onPostsRead: "onAfterListPosts",
+	onPostCreated: "onAfterCreatePost",
+	onPostUpdated: "onAfterUpdatePost",
+	onPostDeleted: "onAfterDeletePost",
+	onNextPreviousPostsRead: "onAfterGetNextPreviousPosts",
+	onListPostsError: "onErrorListPosts",
+	onNextPreviousPostsError: "onErrorGetNextPreviousPosts",
+	onCreatePostError: "onErrorCreatePost",
+	onUpdatePostError: "onErrorUpdatePost",
+	onDeletePostError: "onErrorDeletePost",
+} as const);

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

@@ -83,6 +83,8 @@ async function findOrCreateTags(
  * `slug` must already be slugified by the caller.
  */
 export interface CreatePostInput {
+	/** Trusted author identity assigned by the authorized operation. */
+	authorId?: string;
 	title: string;
 	content: string;
 	excerpt: string;
@@ -114,11 +116,17 @@ export interface UpdatePostInput {
 	tags?: TagInput[];
 }
 
+/** Optional atomic preconditions for a post update. */
+export interface UpdatePostOptions {
+	/** Update only when the stored publish state still matches this value. */
+	expectedPublished?: boolean;
+}
+
 /**
  * Create a new blog post with optional tag associations.
  * Pure DB function — no hooks, no HTTP context. Safe for server-side and SSG use.
  *
- * @remarks **Security:** Authorization hooks (e.g. `onBeforeCreatePost`) are NOT
+ * @remarks **Security:** Operation authorization and lifecycle hooks are NOT
  * called. The caller is responsible for any access-control checks before
  * invoking this function.
  *
@@ -168,28 +176,41 @@ export async function createPost(
 
 /**
  * Update an existing blog post and reconcile its tag associations.
- * Returns `null` if no post with the given `id` exists.
+ * Returns `null` if no post with the given `id` exists or an optional state
+ * precondition no longer matches.
  * Pure DB function — no hooks, no HTTP context. Safe for server-side use.
  *
- * @remarks **Security:** Authorization hooks (e.g. `onBeforeUpdatePost`) are NOT
+ * @remarks **Security:** Operation authorization and lifecycle 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 post ID to update
  * @param input - Partial post data to apply; `slug` must be pre-slugified if provided
+ * @param options - Optional state that must still match when the write executes
  */
 export async function updatePost(
 	adapter: Adapter,
 	id: string,
 	input: UpdatePostInput,
+	options?: UpdatePostOptions,
 ): Promise<Post | null> {
 	const { tags: tagInputs, ...postData } = input;
 
 	return adapter.transaction(async (tx) => {
 		const updatedPost = await tx.update<Post>({
 			model: "post",
-			where: [{ field: "id", value: id }],
+			where: [
+				{ field: "id", value: id },
+				...(options?.expectedPublished === undefined
+					? []
+					: [
+							{
+								field: "published" as const,
+								value: options.expectedPublished,
+							},
+						]),
+			],
 			update: {
 				...postData,
 				updatedAt: new Date(),
@@ -272,7 +293,7 @@ export async function updatePost(
  * Delete a blog post by ID.
  * Pure DB function — no hooks, no HTTP context. Safe for server-side use.
  *
- * @remarks **Security:** Authorization hooks (e.g. `onBeforeDeletePost`) are NOT
+ * @remarks **Security:** Operation authorization and lifecycle hooks are NOT
  * called. The caller is responsible for any access-control checks before
  * invoking this function.
  *