create-nextblock 0.15.10 → 0.16.2

package/templates/nextblock-template/app/actions/visibilityActions.ts

@@ -1,210 +1,210 @@
-"use server";
-
-/**
- * Visibility actions — the ONLY writes that can change what the public sees.
- *
- * These deliberately bypass the Live Draft pipeline (`content_drafts` /
- * `product_drafts`) entirely: they read nothing from a draft, create nothing, and
- * leave any pending content edits exactly where they are. Publishing a page and
- * publishing your unsaved edits are two different decisions, so they are two
- * different code paths.
- *
- * Visibility is stored as the (status, published_at) pair — see
- * `libs/utils/src/lib/publishing.ts` for how "scheduled" is derived from it.
- */
-
-import { createClient } from "@nextblock-cms/db/server";
-import { revalidatePath } from "next/cache";
-import {
-  LIVE_STATUS,
-  isFutureSchedule,
-  resolveVisibilityState,
-  type PublishableType,
-  type VisibilityState,
-} from "@nextblock-cms/utils";
-import { getHomepageTranslationGroupId } from "../lib/homepage";
-
-export interface VisibilityResult {
-  error?: string;
-  state?: VisibilityState;
-  publishedAt?: string | null;
-}
-
-/** What the caller wants the content to become. */
-export type VisibilityIntent =
-  | { action: "publish" }
-  | { action: "schedule"; publishedAt: string }
-  | { action: "unpublish" }
-  | { action: "archive" };
-
-const TABLE: Record<PublishableType, "pages" | "posts" | "products"> = {
-  page: "pages",
-  post: "posts",
-  product: "products",
-};
-
-const CMS_LIST_PATH: Record<PublishableType, string> = {
-  page: "/cms/pages",
-  post: "/cms/posts",
-  product: "/cms/products",
-};
-
-function publicPath(type: PublishableType, slug: string): string {
-  if (type === "post") return `/article/${slug}`;
-  if (type === "product") return `/product/${slug}`;
-  return `/${slug}`;
-}
-
-/**
- * Turn an intent into the columns to write.
- *
- * "Publish" always clears `published_at`. Leaving a past timestamp behind would be
- * harmless for the public gate but would keep rendering as a stale schedule in the
- * CMS; leaving a FUTURE one would mean "Publish now" silently did nothing.
- */
-function buildUpdate(type: PublishableType, intent: VisibilityIntent) {
-  const liveStatus = LIVE_STATUS[type];
-
-  switch (intent.action) {
-    case "publish":
-      return { status: liveStatus, published_at: null };
-    case "schedule":
-      return { status: liveStatus, published_at: intent.publishedAt };
-    case "unpublish":
-      return { status: "draft", published_at: null };
-    case "archive":
-      return { status: "archived", published_at: null };
-  }
-}
-
-/**
- * Set a page/post/product's visibility directly on its row.
- *
- * `id` is a number for pages and posts, a uuid string for products.
- */
-export async function setContentVisibility(
-  type: PublishableType,
-  id: number | string,
-  intent: VisibilityIntent,
-): Promise<VisibilityResult> {
-  const supabase = createClient();
-  const {
-    data: { user },
-  } = await supabase.auth.getUser();
-  if (!user) {
-    return { error: "You must be signed in to change visibility." };
-  }
-
-  const { data: profile } = await supabase
-    .from("profiles")
-    .select("role")
-    .eq("id", user.id)
-    .single();
-  if (!profile || !["ADMIN", "WRITER"].includes(profile.role)) {
-    return { error: "You do not have permission to change visibility." };
-  }
-
-  if (intent.action === "schedule" && !isFutureSchedule(intent.publishedAt)) {
-    return { error: "Pick a date and time in the future, or publish now instead." };
-  }
-
-  const update = buildUpdate(type, intent);
-  const { data: row, error } = await supabase
-    .from(TABLE[type])
-    .update({ ...update, updated_at: new Date().toISOString() } as never)
-    .eq("id", id as never)
-    .select("slug, status, published_at, translation_group_id")
-    .single();
-
-  if (error || !row) {
-    return { error: error?.message || "Could not update visibility." };
-  }
-
-  const updated = row as unknown as {
-    slug: string | null;
-    status: string;
-    published_at: string | null;
-    translation_group_id: string | null;
-  };
-
-  revalidatePath(CMS_LIST_PATH[type]);
-  revalidatePath(`${CMS_LIST_PATH[type]}/${id}/edit`);
-
-  if (updated.slug) {
-    revalidatePath(publicPath(type, updated.slug));
-  }
-
-  // Every language variation of the homepage is also served at "/", whatever its
-  // slug, so taking one down (or putting it up) has to bust that cache too.
-  if (type === "page") {
-    const homepageGroupId = await getHomepageTranslationGroupId(supabase);
-    if (
-      (homepageGroupId && updated.translation_group_id === homepageGroupId) ||
-      updated.slug === "home"
-    ) {
-      revalidatePath("/");
-    }
-  }
-
-  if (type === "post") {
-    revalidatePath("/articles");
-  }
-
-  return {
-    state: resolveVisibilityState({
-      status: updated.status,
-      publishedAt: updated.published_at,
-      liveStatus: LIVE_STATUS[type],
-    }),
-    publishedAt: updated.published_at,
-  };
-}
-
-/**
- * Sibling-language versions of the same content, with their visibility state.
- *
- * Status is per-row, so publishing the French page does nothing for English. The
- * publish dialog shows this list to catch the half-published translation — the
- * single most common multilingual mistake.
- */
-export interface SiblingVisibility {
-  id: number | string;
-  languageId: number;
-  title: string;
-  state: VisibilityState;
-}
-
-export async function getSiblingVisibility(
-  type: PublishableType,
-  translationGroupId: string,
-  excludeId: number | string,
-): Promise<SiblingVisibility[]> {
-  if (!translationGroupId) return [];
-
-  const supabase = createClient();
-  const { data, error } = await supabase
-    .from(TABLE[type])
-    .select("id, title, language_id, status, published_at")
-    .eq("translation_group_id", translationGroupId);
-
-  if (error || !data) return [];
-
-  return (data as unknown as Array<{
-    id: number | string;
-    title: string;
-    language_id: number;
-    status: string;
-    published_at: string | null;
-  }>)
-    .filter((row) => String(row.id) !== String(excludeId))
-    .map((row) => ({
-      id: row.id,
-      languageId: row.language_id,
-      title: row.title,
-      state: resolveVisibilityState({
-        status: row.status,
-        publishedAt: row.published_at,
-        liveStatus: LIVE_STATUS[type],
-      }),
-    }));
-}
+"use server";
+
+/**
+ * Visibility actions — the ONLY writes that can change what the public sees.
+ *
+ * These deliberately bypass the Live Draft pipeline (`content_drafts` /
+ * `product_drafts`) entirely: they read nothing from a draft, create nothing, and
+ * leave any pending content edits exactly where they are. Publishing a page and
+ * publishing your unsaved edits are two different decisions, so they are two
+ * different code paths.
+ *
+ * Visibility is stored as the (status, published_at) pair — see
+ * `libs/utils/src/lib/publishing.ts` for how "scheduled" is derived from it.
+ */
+
+import { createClient } from "@nextblock-cms/db/server";
+import { revalidatePath } from "next/cache";
+import {
+  LIVE_STATUS,
+  isFutureSchedule,
+  resolveVisibilityState,
+  type PublishableType,
+  type VisibilityState,
+} from "@nextblock-cms/utils";
+import { getHomepageTranslationGroupId } from "../lib/homepage";
+
+export interface VisibilityResult {
+  error?: string;
+  state?: VisibilityState;
+  publishedAt?: string | null;
+}
+
+/** What the caller wants the content to become. */
+export type VisibilityIntent =
+  | { action: "publish" }
+  | { action: "schedule"; publishedAt: string }
+  | { action: "unpublish" }
+  | { action: "archive" };
+
+const TABLE: Record<PublishableType, "pages" | "posts" | "products"> = {
+  page: "pages",
+  post: "posts",
+  product: "products",
+};
+
+const CMS_LIST_PATH: Record<PublishableType, string> = {
+  page: "/cms/pages",
+  post: "/cms/posts",
+  product: "/cms/products",
+};
+
+function publicPath(type: PublishableType, slug: string): string {
+  if (type === "post") return `/article/${slug}`;
+  if (type === "product") return `/product/${slug}`;
+  return `/${slug}`;
+}
+
+/**
+ * Turn an intent into the columns to write.
+ *
+ * "Publish" always clears `published_at`. Leaving a past timestamp behind would be
+ * harmless for the public gate but would keep rendering as a stale schedule in the
+ * CMS; leaving a FUTURE one would mean "Publish now" silently did nothing.
+ */
+function buildUpdate(type: PublishableType, intent: VisibilityIntent) {
+  const liveStatus = LIVE_STATUS[type];
+
+  switch (intent.action) {
+    case "publish":
+      return { status: liveStatus, published_at: null };
+    case "schedule":
+      return { status: liveStatus, published_at: intent.publishedAt };
+    case "unpublish":
+      return { status: "draft", published_at: null };
+    case "archive":
+      return { status: "archived", published_at: null };
+  }
+}
+
+/**
+ * Set a page/post/product's visibility directly on its row.
+ *
+ * `id` is a number for pages and posts, a uuid string for products.
+ */
+export async function setContentVisibility(
+  type: PublishableType,
+  id: number | string,
+  intent: VisibilityIntent,
+): Promise<VisibilityResult> {
+  const supabase = createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+  if (!user) {
+    return { error: "You must be signed in to change visibility." };
+  }
+
+  const { data: profile } = await supabase
+    .from("profiles")
+    .select("role")
+    .eq("id", user.id)
+    .single();
+  if (!profile || !["ADMIN", "WRITER"].includes(profile.role)) {
+    return { error: "You do not have permission to change visibility." };
+  }
+
+  if (intent.action === "schedule" && !isFutureSchedule(intent.publishedAt)) {
+    return { error: "Pick a date and time in the future, or publish now instead." };
+  }
+
+  const update = buildUpdate(type, intent);
+  const { data: row, error } = await supabase
+    .from(TABLE[type])
+    .update({ ...update, updated_at: new Date().toISOString() } as never)
+    .eq("id", id as never)
+    .select("slug, status, published_at, translation_group_id")
+    .single();
+
+  if (error || !row) {
+    return { error: error?.message || "Could not update visibility." };
+  }
+
+  const updated = row as unknown as {
+    slug: string | null;
+    status: string;
+    published_at: string | null;
+    translation_group_id: string | null;
+  };
+
+  revalidatePath(CMS_LIST_PATH[type]);
+  revalidatePath(`${CMS_LIST_PATH[type]}/${id}/edit`);
+
+  if (updated.slug) {
+    revalidatePath(publicPath(type, updated.slug));
+  }
+
+  // Every language variation of the homepage is also served at "/", whatever its
+  // slug, so taking one down (or putting it up) has to bust that cache too.
+  if (type === "page") {
+    const homepageGroupId = await getHomepageTranslationGroupId(supabase);
+    if (
+      (homepageGroupId && updated.translation_group_id === homepageGroupId) ||
+      updated.slug === "home"
+    ) {
+      revalidatePath("/");
+    }
+  }
+
+  if (type === "post") {
+    revalidatePath("/articles");
+  }
+
+  return {
+    state: resolveVisibilityState({
+      status: updated.status,
+      publishedAt: updated.published_at,
+      liveStatus: LIVE_STATUS[type],
+    }),
+    publishedAt: updated.published_at,
+  };
+}
+
+/**
+ * Sibling-language versions of the same content, with their visibility state.
+ *
+ * Status is per-row, so publishing the French page does nothing for English. The
+ * publish dialog shows this list to catch the half-published translation — the
+ * single most common multilingual mistake.
+ */
+export interface SiblingVisibility {
+  id: number | string;
+  languageId: number;
+  title: string;
+  state: VisibilityState;
+}
+
+export async function getSiblingVisibility(
+  type: PublishableType,
+  translationGroupId: string,
+  excludeId: number | string,
+): Promise<SiblingVisibility[]> {
+  if (!translationGroupId) return [];
+
+  const supabase = createClient();
+  const { data, error } = await supabase
+    .from(TABLE[type])
+    .select("id, title, language_id, status, published_at")
+    .eq("translation_group_id", translationGroupId);
+
+  if (error || !data) return [];
+
+  return (data as unknown as Array<{
+    id: number | string;
+    title: string;
+    language_id: number;
+    status: string;
+    published_at: string | null;
+  }>)
+    .filter((row) => String(row.id) !== String(excludeId))
+    .map((row) => ({
+      id: row.id,
+      languageId: row.language_id,
+      title: row.title,
+      state: resolveVisibilityState({
+        status: row.status,
+        publishedAt: row.published_at,
+        liveStatus: LIVE_STATUS[type],
+      }),
+    }));
+}

package/templates/nextblock-template/app/api/ai/seo/alt-text/route.ts

@@ -0,0 +1,221 @@
+import { NextResponse } from 'next/server';
+
+import { createClient, verifyPackageOnline } from '@nextblock-cms/db/server';
+
+import { generateCortexAiAltText } from '@nextblock-cms/cortex';
+import {
+  safeParseCortexAiModelSelection,
+  summarizeCortexAiRoutingError,
+} from '@nextblock-cms/cortex';
+
+import { z } from '../../../../../lib/zod-config';
+
+export const dynamic = 'force-dynamic';
+
+type SupabaseServerClient = ReturnType<typeof createClient>;
+
+/**
+ * The request contract for the alt-text endpoint.
+ *
+ * `z.strictObject` rather than `z.object`, for the same reason the rest of the
+ * Cortex surface uses it: an unknown key is almost always a caller that has drifted
+ * from the contract — a stale client still sending `mediaId`, or a hand-rolled
+ * fetch that guessed at the field names — and silently discarding it produces a
+ * generation that ignores half of what the caller asked for. Rejecting loudly at
+ * the boundary turns that into a 400 the developer can actually read.
+ *
+ * `maxLength` is validated only for shape (a positive integer), not for range. The
+ * engine in `ai-vision.ts` deliberately CLAMPS an out-of-range budget into its own
+ * 20..1000 bounds instead of throwing, precisely so that a careless call site
+ * cannot break a media upload flow; duplicating those bounds here would both
+ * contradict that decision and leave two copies of the same numbers free to drift
+ * apart.
+ */
+const altTextRequestSchema = z.strictObject({
+  context: z.string().max(2000).optional(),
+  imageUrl: z.string().min(1),
+  maxLength: z.number().int().positive().optional(),
+});
+
+async function requireCmsWriterAccess(supabase: SupabaseServerClient) {
+  const {
+    data: { user },
+    error: userError,
+  } = await supabase.auth.getUser();
+
+  if (userError || !user) {
+    return null;
+  }
+
+  const { data: profile, error: profileError } = await supabase
+    .from('profiles')
+    .select('role')
+    .eq('id', user.id)
+    .single();
+
+  if (profileError || !profile || !['ADMIN', 'WRITER'].includes(profile.role)) {
+    return null;
+  }
+
+  return { userId: user.id };
+}
+
+function jsonError(message: string, status: number) {
+  return NextResponse.json({ error: message }, { status });
+}
+
+/**
+ * Return a human-readable reason the supplied image URL cannot be sent to a vision
+ * model, or `null` when it is usable.
+ *
+ * This duplicates a check that `generateCortexAiAltText` also performs, and it does
+ * so deliberately. The engine's copy throws, which would surface here as a 500 —
+ * the status code that means "the server broke" — when the truth is that the caller
+ * sent an unusable value and needs a 400 telling them exactly that. Running the
+ * check first gives the common mistake the right status and an actionable message,
+ * while the engine keeps its own guard for every other call site.
+ *
+ * The mistake being guarded against is concrete rather than hypothetical:
+ * `resolveMediaUrl()` returns a bare `/${objectKey}` whenever no R2 base URL is
+ * configured, so an install that has not finished its media setup hands every
+ * caller a site-relative path. Because the Cortex OpenRouter provider is created
+ * without `supportedUrls`, the AI SDK does not forward a link to the model — it
+ * downloads the image server-side and inlines it as base64 — so a relative path
+ * would fail inside the SDK's own fetch, once per model in the fallback chain, with
+ * an error that never mentions the actual problem.
+ *
+ * The scheme test is strict rather than allowlist-based: any absolute URL is
+ * acceptable as long as it is http or https, but `file:`, `data:`, and `blob:` are
+ * refused. Those are the schemes that would either read the server's own disk or
+ * push an unbounded inline payload through every model in the fallback chain.
+ */
+function describeUnusableImageUrl(imageUrl: string): string | null {
+  const trimmed = imageUrl.trim();
+
+  if (!trimmed) {
+    return 'An image URL is required to generate alt text.';
+  }
+
+  let parsed: URL;
+
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return `Alt text generation needs an absolute http(s) image URL, but received "${trimmed}". A storage key or site-relative path has to be resolved to a publicly fetchable URL first, because the model provider downloads the image server-side rather than following the link.`;
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return `Alt text generation needs an http(s) image URL, but received the "${parsed.protocol}" scheme.`;
+  }
+
+  return null;
+}
+
+export async function POST(request: Request) {
+  try {
+    const supabase = createClient();
+    const access = await requireCmsWriterAccess(supabase);
+
+    if (!access) {
+      return jsonError('You do not have permission to generate image alt text.', 403);
+    }
+
+    // The package gate that /api/ai/generate-blocks is missing (docs/08 follow-up
+    // #6). Alt-text generation is a paid Cortex AI feature that burns either the
+    // operator's own OpenRouter credit or the shared house key, so an install
+    // without an active `cortex-ai` activation must not reach a model at all. The
+    // package id is `cortex-ai`; `ai` is not a package id anywhere in this system.
+    const isCortexAiActive = await verifyPackageOnline('cortex-ai');
+
+    if (!isCortexAiActive) {
+      return jsonError('NextBlock Cortex AI is not active for this workspace.', 403);
+    }
+
+    const body = await request.json().catch(() => null);
+    const parsedRequest = altTextRequestSchema.safeParse(body);
+
+    if (!parsedRequest.success) {
+      return jsonError('Invalid Cortex AI alt text request.', 400);
+    }
+
+    const unusableImageUrlReason = describeUnusableImageUrl(parsedRequest.data.imageUrl);
+
+    if (unusableImageUrlReason) {
+      return jsonError(unusableImageUrlReason, 400);
+    }
+
+    // Sandbox installs have no server-side OpenRouter credential at all: the demo
+    // visitor pastes their own key into the browser, it lives in localStorage under
+    // `cortex_ai_sandbox_openrouter_api_key`, and it rides along on these headers.
+    // The env guard matters as much as the headers do — outside a sandbox the
+    // server must never accept a caller-supplied credential, because that would let
+    // any authenticated writer redirect generation through a key the operator never
+    // chose.
+    const sandboxKey =
+      process.env.NEXT_PUBLIC_IS_SANDBOX === 'true'
+        ? request.headers.get('x-sandbox-openrouter-key')
+        : null;
+    const sandboxModelRaw =
+      process.env.NEXT_PUBLIC_IS_SANDBOX === 'true'
+        ? request.headers.get('x-sandbox-openrouter-model')
+        : null;
+
+    let modelSelection = null;
+    if (sandboxModelRaw) {
+      try {
+        modelSelection = safeParseCortexAiModelSelection(JSON.parse(sandboxModelRaw));
+      } catch {
+        // Ignore malformed sandbox model headers.
+      }
+    }
+
+    // `generateCortexAiAltText` takes a requested model id rather than a whole
+    // stored selection, because its vision routing policy has to decide for itself
+    // whether an id is plausibly multimodal before it will route an image to it.
+    // The header is still parsed through `safeParseCortexAiModelSelection` so that
+    // a malformed value is discarded rather than forwarded as a bogus id, and the
+    // id is only honoured alongside the sandbox key so that a caller-supplied model
+    // choice can never be applied to the operator's own credential.
+    const result = await generateCortexAiAltText({
+      apiKey: sandboxKey || undefined,
+      context: parsedRequest.data.context,
+      imageUrl: parsedRequest.data.imageUrl,
+      maxLength: parsedRequest.data.maxLength,
+      modelId: sandboxKey && modelSelection ? modelSelection.modelId : undefined,
+    });
+
+    return NextResponse.json(
+      {
+        altText: result.altText,
+        credentialSource: result.credentialSource,
+        modelId: result.modelId,
+      },
+      {
+        headers: {
+          'x-cortex-ai-credential-source': result.credentialSource,
+          'x-cortex-ai-model': result.modelId,
+        },
+      }
+    );
+  } catch (error) {
+    // A CortexAiRoutingError is recognised STRUCTURALLY rather than with
+    // `instanceof`. The class is defined in @nextblock-cms/cortex, which resolves to
+    // library source inside this monorepo but to a published package in a
+    // standalone install; when both shapes end up in one bundle the two class
+    // identities are not the same object and `instanceof` silently returns false,
+    // swallowing the per-model attempt log that is the only useful diagnostic for a
+    // routing failure.
+    if (error && typeof error === 'object' && 'attempts' in error) {
+      console.error(
+        '[Cortex AI] Failed to generate alt text after model attempts:',
+        JSON.stringify((error as { attempts: unknown }).attempts, null, 2)
+      );
+    }
+
+    console.error('[Cortex AI] Failed to generate alt text:', error);
+    return jsonError(
+      summarizeCortexAiRoutingError(error, 'Failed to generate image alt text.'),
+      500
+    );
+  }
+}