create-nextblock 0.15.9 → 0.16.1

package/templates/nextblock-template/app/robots.ts

@@ -0,0 +1,123 @@
+import type { MetadataRoute } from 'next';
+import { getSsgSupabaseClient } from '@nextblock-cms/db/server';
+import { normalizeRobotsSettings, type RobotsSettings } from '@nextblock-cms/utils/seo';
+import { buildRobotsMetadata } from '../lib/seo/robots-txt';
+import { resolveSiteUrl, hasResolvedSiteUrl } from '../lib/site-url';
+
+/**
+ * /robots.txt, generated from the operator's stored settings.
+ *
+ * This replaces the hand-rolled `app/robots.txt/route.ts` that used to live here,
+ * and the two CANNOT coexist: Next's `normalizeMetadataRoute` rewrites the page
+ * `/robots` to `/robots.txt` and then appends `/route`, which is character for
+ * character the app path the old handler occupied. Keeping both would be a
+ * duplicate-route collision, not a fallback — so the old file was deleted in the
+ * same change that added this one. The externally visible path is unchanged, which
+ * is why `isSetupAllowlisted()` in proxy.ts still allowlists the literal
+ * '/robots.txt' and needed no edit.
+ *
+ * The move from a route handler to the metadata route is what buys the caching
+ * below. Everything else about the response — the served path, the content type, the
+ * sandbox behaviour — is identical to what shipped before.
+ */
+
+/**
+ * Cache the generated file and rebuild it at most once an hour, mirroring
+ * app/sitemap.ts. Crawlers get a fast, statically-served response while a change an
+ * operator saves in /cms/settings still takes effect without a redeploy.
+ *
+ * NextBlock does not enable Next.js Cache Components, so the route-segment
+ * `revalidate` config is the idiomatic caching control here. If `cacheComponents`
+ * were turned on, the equivalent would be a `'use cache'` body paired with
+ * `cacheLife('hours')` instead of this export.
+ */
+export const revalidate = 3600;
+
+/**
+ * The `site_settings` row the SEO screen writes, seeded by migration 30 and moved into
+ * the ADMIN-only write group by migration 31 — a WRITER could otherwise have PATCHed
+ * this row through PostgREST and de-indexed the whole site, since RLS, not the server
+ * action, is the boundary that actually holds.
+ */
+const ROBOTS_SETTINGS_KEY = 'seo_robots_settings';
+
+/**
+ * Reads the stored robots configuration, falling back to the permissive defaults on
+ * any failure whatsoever.
+ *
+ * The anon client is the right one here, and deliberately so: `seo_robots_settings`
+ * is a non-secret key and `site_settings`' read policy is already public for
+ * non-secret keys, so nothing on this path needs the service role. Handing a
+ * service-role client to a route that anonymous crawlers hit would be a needless
+ * escalation.
+ *
+ * That read has to stay anonymous, which is why migration 31 tightened only the
+ * INSERT/UPDATE/DELETE policies and left `site_settings_read_policy` alone. Adding
+ * this key to the read policy's sensitive array would not fail loudly — the query
+ * below would simply return no row, every crawler would be served the permissive
+ * defaults, and the operator's configuration would stop applying without a single
+ * error anywhere.
+ *
+ * The failure handling matters more than it looks. A crawler that receives a 500 for
+ * robots.txt may treat the entire site as disallowed until it next succeeds, so an
+ * unreachable database — or a `cms_redirects`-era install that has not yet run
+ * `npm run db:migrate`, where this settings row does not exist — must produce a
+ * valid, permissive file rather than an error. `normalizeRobotsSettings` handles the
+ * other half of that: whatever jsonb hands back, including null, a string or a
+ * half-migrated object, becomes a complete `RobotsSettings`.
+ */
+async function loadRobotsSettings(): Promise<RobotsSettings> {
+  try {
+    const supabase = getSsgSupabaseClient();
+    const { data, error } = await supabase
+      .from('site_settings')
+      .select('value')
+      .eq('key', ROBOTS_SETTINGS_KEY)
+      .maybeSingle();
+
+    if (error) {
+      console.error('robots.txt: failed to read the robots settings; serving defaults.', error);
+      return normalizeRobotsSettings(undefined);
+    }
+
+    // A missing row is not an error — it is a site whose operator has never opened
+    // the SEO screen — and the defaults are exactly what that site should serve.
+    return normalizeRobotsSettings(data?.value);
+  } catch (error) {
+    console.error('robots.txt: robots settings lookup threw; serving defaults.', error);
+    return normalizeRobotsSettings(undefined);
+  }
+}
+
+export default async function robots(): Promise<MetadataRoute.Robots> {
+  const isSandbox = process.env.NEXT_PUBLIC_IS_SANDBOX === 'true';
+
+  // The sandbox answer ignores every stored setting, so there is nothing to read.
+  // Skipping the query keeps a disposable deployment's robots.txt working even when
+  // its database is asleep or being reset by the cron job. The reasoning for why the
+  // sandbox ALLOWS crawling rather than disallowing it lives on SANDBOX_USER_AGENT_RULE
+  // in lib/seo/robots-txt.ts — it is the counter-intuitive part of this feature and
+  // that is where it is written down in full.
+  if (isSandbox) {
+    return buildRobotsMetadata(normalizeRobotsSettings(undefined), {
+      isSandbox: true,
+      sitemapUrl: null,
+    });
+  }
+
+  // Explicit NEXT_PUBLIC_URL → Vercel production URL → local-dev fallback.
+  const siteUrl = resolveSiteUrl();
+
+  if (!hasResolvedSiteUrl()) {
+    console.warn(
+      'Warning: no site URL is set for robots.txt (NEXT_PUBLIC_URL / Vercel production URL). Defaulting to http://localhost:3000. Set NEXT_PUBLIC_URL for production.'
+    );
+  }
+
+  const settings = await loadRobotsSettings();
+
+  return buildRobotsMetadata(settings, {
+    isSandbox: false,
+    sitemapUrl: `${siteUrl}/sitemap.xml`,
+  });
+}

package/templates/nextblock-template/app/sitemap.ts

@@ -70,7 +70,7 @@ async function safe(
 
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   // Disposable sandbox deployments should not advertise an indexable sitemap
-  // (mirrors the legacy app/sitemap.xml route and app/robots.txt).
+  // (mirrors the legacy app/sitemap.xml route and app/robots.ts).
   if (process.env.NEXT_PUBLIC_IS_SANDBOX === 'true') {
     return [];
   }

package/templates/nextblock-template/components/seo/GenerateMetaButton.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+import { useState } from 'react';
+import { Loader2, Sparkles } from 'lucide-react';
+import { toast } from 'sonner';
+import { Button } from '@nextblock-cms/ui';
+
+import { buildCortexAiRequestHeaders } from '../../lib/cortex-ai/sandbox-headers';
+
+/**
+ * The four strings `/api/ai/seo/metadata` writes back.
+ *
+ * Note what is NOT here: an image. The Open Graph image on a page or post is derived from
+ * `feature_image_id`, and nothing in this flow changes that. The model writes copy; the
+ * operator picks the picture.
+ */
+export interface GeneratedSeoMetadata {
+  metaDescription: string;
+  metaTitle: string;
+  ogDescription: string;
+  ogTitle: string;
+}
+
+interface GenerateMetaButtonProps {
+  /**
+   * Body prose the model reads in order to write about the page. The caller flattens its
+   * blocks; an empty string disables the button, because a model asked to summarize
+   * nothing invents something, and invented metadata is worse than none.
+   */
+  content: string;
+  /** Optional term the copy should be built around, when the caller knows one. */
+  focusKeyword?: string | null;
+  /** Language code (`en`, `fr`, …) so the copy comes back in the content's language. */
+  locale?: string | null;
+  onGenerated: (result: GeneratedSeoMetadata) => void;
+  /** Site title, when cheaply available, so the model can shape a title that suffixes well. */
+  siteTitle?: string | null;
+  /** The page's own title — the strongest single hint about what the page is. */
+  title?: string | null;
+}
+
+/**
+ * Guard against a mistake that would otherwise be silent: if the route ever answers 200
+ * with a partial body, writing `undefined` into a controlled input flips it to
+ * uncontrolled and React warns once, at runtime, in a place far from the cause. Coercing
+ * here means a malformed response degrades to empty strings the operator can see.
+ */
+function readString(payload: Record<string, unknown>, key: string): string {
+  const value = payload[key];
+  return typeof value === 'string' ? value : '';
+}
+
+export default function GenerateMetaButton({
+  content,
+  focusKeyword,
+  locale,
+  onGenerated,
+  siteTitle,
+  title,
+}: GenerateMetaButtonProps) {
+  const [isGenerating, setIsGenerating] = useState(false);
+
+  const trimmedContent = content.trim();
+  const canGenerate = trimmedContent.length > 0 && !isGenerating;
+
+  const handleGenerate = async () => {
+    if (!canGenerate) {
+      return;
+    }
+
+    setIsGenerating(true);
+
+    try {
+      const response = await fetch('/api/ai/seo/metadata', {
+        // Optional fields are omitted rather than sent as null: the contract types them
+        // as `string | undefined`, and a null would be a different, likely rejected, value.
+        body: JSON.stringify({
+          content: trimmedContent,
+          ...(focusKeyword?.trim() ? { focusKeyword: focusKeyword.trim() } : {}),
+          ...(locale?.trim() ? { locale: locale.trim() } : {}),
+          ...(siteTitle?.trim() ? { siteTitle: siteTitle.trim() } : {}),
+          ...(title?.trim() ? { title: title.trim() } : {}),
+        }),
+        headers: buildCortexAiRequestHeaders(),
+        method: 'POST',
+      });
+
+      const payload = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+
+      if (!response.ok || !payload) {
+        // Every error shape from these routes is `{ error: string }` at 400/403/500, so a
+        // missing `error` means something upstream of the route failed (a proxy, a crash
+        // before the handler) and a generic message is the honest thing to show.
+        const message =
+          payload && typeof payload['error'] === 'string'
+            ? (payload['error'] as string)
+            : 'Cortex AI could not generate metadata.';
+        throw new Error(message);
+      }
+
+      onGenerated({
+        metaDescription: readString(payload, 'metaDescription'),
+        metaTitle: readString(payload, 'metaTitle'),
+        ogDescription: readString(payload, 'ogDescription'),
+        ogTitle: readString(payload, 'ogTitle'),
+      });
+      toast.success('Cortex AI drafted your SEO metadata.');
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Cortex AI could not generate metadata.');
+    } finally {
+      setIsGenerating(false);
+    }
+  };
+
+  return (
+    <Button
+      className="h-7 gap-1.5 px-2 text-[11px]"
+      disabled={!canGenerate}
+      onClick={handleGenerate}
+      size="sm"
+      title={
+        trimmedContent
+          ? 'Draft the meta title and description from this page’s content'
+          : 'Add some content to this page first — Cortex AI needs something to summarize'
+      }
+      type="button"
+      variant="outline"
+    >
+      {isGenerating ? (
+        <Loader2 aria-hidden="true" className="h-3.5 w-3.5 animate-spin" />
+      ) : (
+        <Sparkles aria-hidden="true" className="h-3.5 w-3.5 text-amber-500" />
+      )}
+      {isGenerating ? 'Generating…' : 'Generate Meta Data with AI'}
+    </Button>
+  );
+}

package/templates/nextblock-template/components/seo/PageSeoAuditSection.tsx

@@ -0,0 +1,244 @@
+'use client';
+
+/**
+ * The page-level SEO audit, as it appears on the page and post edit screens.
+ *
+ * WHAT THIS IS FOR. `SeoAuditPanel` grades whatever document it is handed; this
+ * component is the thing that decides *which* document that is on an edit screen
+ * and how much room the result is allowed to take. It reads the shared
+ * `PageSeoProvider` state — the live block array published by `BlockEditorArea`
+ * and the meta title and description published by the page or post form — merges
+ * them with `buildPageSeoDocument`, and hands the result to the panel at page
+ * scope. That merge is the entire point of the feature: headings live both in
+ * standalone `heading` blocks and inside a text block's HTML, and section blocks
+ * carry more blocks in their columns, so "does this page have exactly one H1"
+ * simply cannot be answered from inside one block editor.
+ *
+ * WHY IT IS COLLAPSED BY DEFAULT. The block editor is the reason anyone opens
+ * this screen. A full analysis panel expanded above it would push the first
+ * block below the fold on a laptop every time, which is a tax paid on every
+ * edit for a report most sessions never read. Collapsed, the section is a single
+ * row: the score, the number of findings, and a button. That row is enough to
+ * decide whether the report is worth opening, which is all a summary owes you.
+ *
+ * WHY THE PANEL STAYS MOUNTED WHILE COLLAPSED. The summary row shows a live
+ * score, and the only honest way to have one is to let the panel keep computing
+ * it — so the collapsed state hides the detail with `hidden` rather than
+ * unmounting the panel, and the panel reports each result back through
+ * `onAuditChange`. Unmounting instead would either freeze the summary at its
+ * last value or force this component to run a second, competing audit that could
+ * disagree with the one behind the toggle.
+ *
+ * WHY THE DOCUMENT IS REBUILT ON A DELAY. `blocks` is a new array on every
+ * keystroke in any block editor, and rebuilding the page document means walking
+ * every block and parsing every rich-text body. Doing that during the render of
+ * each keystroke would be pure waste, since only the last one is ever graded. The
+ * rebuild is therefore deferred to the same trailing pause the panel already
+ * waits for, which does mean the page score settles roughly two debounce
+ * intervals after typing stops — a deliberate trade of latency nobody is watching
+ * for work nobody needs.
+ *
+ * Rendering nothing without a provider is intentional, not defensive padding:
+ * the same edit-screen components are reachable from the product editor, which
+ * has no page-level audit, and `usePageSeo()` returning `null` is the supported
+ * way that surface says so.
+ */
+
+import * as React from 'react';
+
+import { Button } from '@nextblock-cms/ui';
+import { cn } from '@nextblock-cms/utils';
+import type { SeoAuditResult, SeoScoreBand } from '@nextblock-cms/utils/seo';
+import { ChevronDown, ChevronUp, Gauge } from 'lucide-react';
+
+import { useCortexAiActive } from '../../app/cms/components/CortexAiActiveContext';
+import { usePageSeo } from '../../lib/seo/page-audit-context';
+import { buildPageSeoDocument } from '../../lib/seo/page-document';
+import { SEO_LIVE_AUDIT_DEBOUNCE_MS, SeoAuditPanel } from './SeoAuditPanel';
+
+/**
+ * Where the open/closed choice is remembered.
+ *
+ * Per-browser like the block editor's own panel toggle, and for the same reason:
+ * it is a workspace preference in the family of a collapsed sidebar, not content,
+ * and persisting it server-side would mean a write on every click.
+ */
+const PAGE_SEO_PANEL_STORAGE_KEY = 'nextblock_page_seo_audit_open';
+
+/**
+ * Badge colours for the collapsed summary, following the CMS convention: emerald
+ * for fine, amber for a caution, red for a failure. `excellent` and `good` share
+ * emerald because the distinction between them is carried by the number itself.
+ */
+const BAND_BADGE_STYLE: Record<SeoScoreBand, string> = {
+  excellent: 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-400',
+  fair: 'bg-amber-500/15 text-amber-700 dark:text-amber-400',
+  good: 'bg-emerald-500/15 text-emerald-700 dark:text-emerald-400',
+  poor: 'bg-red-500/15 text-red-700 dark:text-red-400',
+};
+
+export interface PageSeoAuditSectionProps {
+  className?: string;
+}
+
+export function PageSeoAuditSection({ className }: PageSeoAuditSectionProps) {
+  const pageSeo = usePageSeo();
+  const detailsId = React.useId();
+  /**
+   * Forwarded so the panel can explain where the one-click fixes went.
+   *
+   * There is no Fix button at page scope — a page has no single editor to write
+   * a rewrite into — and the panel only says so when Cortex AI is actually
+   * activated. Without this flag an activated install would show nothing at all
+   * where a Fix button sits at block scope, which reads as a bug rather than as
+   * a deliberate absence.
+   */
+  const isCortexAiActive = useCortexAiActive();
+
+  // Read through optional chaining so every hook below runs unconditionally: the
+  // "no provider" case is handled by returning null *after* the hooks, never by
+  // skipping them, which would break the rules of hooks the moment a provider
+  // appeared or disappeared above this component.
+  const liveBlocks = pageSeo?.snapshot.blocks;
+
+  const [audit, setAudit] = React.useState<SeoAuditResult | null>(null);
+  const [isOpen, setIsOpen] = React.useState(false);
+  const [settledBlocks, setSettledBlocks] = React.useState<unknown[]>(() => liveBlocks ?? []);
+
+  /**
+   * Adopt the remembered preference once, after mount.
+   *
+   * Every access is wrapped because `localStorage` does not merely come back
+   * empty in a private window or with site data blocked — the property access
+   * itself throws, and an uncaught throw here would take the whole edit screen
+   * down over a panel toggle. A first visit stays collapsed, which is the state
+   * that keeps the block editor where the author expects to find it.
+   */
+  React.useEffect(() => {
+    try {
+      setIsOpen(window.localStorage.getItem(PAGE_SEO_PANEL_STORAGE_KEY) === 'true');
+    } catch {
+      setIsOpen(false);
+    }
+  }, []);
+
+  const toggleOpen = React.useCallback(() => {
+    setIsOpen((previous) => {
+      const next = !previous;
+      try {
+        window.localStorage.setItem(PAGE_SEO_PANEL_STORAGE_KEY, String(next));
+      } catch {
+        // The preference is a convenience; losing it is not worth an error.
+      }
+      return next;
+    });
+  }, []);
+
+  // The deferred rebuild described in the module docblock. `liveBlocks` changes
+  // identity on every keystroke anywhere in the page, so each change restarts
+  // this timer and only the array that survives a pause is ever walked.
+  React.useEffect(() => {
+    if (liveBlocks === undefined) {
+      return;
+    }
+
+    const timeoutId = window.setTimeout(() => {
+      setSettledBlocks(liveBlocks);
+    }, SEO_LIVE_AUDIT_DEBOUNCE_MS);
+
+    return () => window.clearTimeout(timeoutId);
+  }, [liveBlocks]);
+
+  // Memoised because the document's identity is one of the panel's debounce
+  // dependencies: a fresh object on every render would reset the panel's timer
+  // forever and no score would ever appear.
+  const pageDocument = React.useMemo(() => buildPageSeoDocument(settledBlocks), [settledBlocks]);
+
+  const handleAuditChange = React.useCallback((next: SeoAuditResult | null) => {
+    setAudit(next);
+  }, []);
+
+  if (!pageSeo) {
+    return null;
+  }
+
+  const issueCount = audit?.issues.length ?? 0;
+  const errorCount = audit?.issues.filter((issue) => issue.severity === 'error').length ?? 0;
+  const summary = !audit
+    ? 'Reading every block on this page…'
+    : issueCount === 0
+      ? 'No issues found across this page.'
+      : `${issueCount} ${issueCount === 1 ? 'finding' : 'findings'} across this page` +
+        (errorCount > 0 ? `, ${errorCount} of them ${errorCount === 1 ? 'an error' : 'errors'}.` : '.');
+
+  return (
+    <section className={cn('rounded-lg border bg-background', className)}>
+      <div className="flex flex-wrap items-center justify-between gap-3 p-3">
+        <div className="flex min-w-0 items-center gap-3">
+          <Gauge aria-hidden="true" className="h-5 w-5 shrink-0 text-muted-foreground" />
+          <div className="min-w-0">
+            <h2 className="text-sm font-semibold mt-0">Page SEO analysis</h2>
+            <p className="text-xs text-muted-foreground">{summary}</p>
+          </div>
+        </div>
+
+        <div className="flex shrink-0 items-center gap-3">
+          {audit && (
+            /* The band's colour repeats what the number already says, so it is
+               hidden from assistive technology and spelled out in the button's
+               accessible name instead of being announced twice. */
+            <span
+              aria-hidden="true"
+              className={cn(
+                'rounded-full px-2.5 py-1 text-xs font-semibold tabular-nums',
+                BAND_BADGE_STYLE[audit.scoreBand]
+              )}
+            >
+              {audit.score}/100
+            </span>
+          )}
+          <Button
+            aria-controls={detailsId}
+            aria-expanded={isOpen}
+            className="h-8 text-xs"
+            onClick={toggleOpen}
+            size="sm"
+            type="button"
+            variant="outline"
+          >
+            {isOpen ? (
+              <ChevronUp aria-hidden="true" className="mr-1.5 h-4 w-4" />
+            ) : (
+              <ChevronDown aria-hidden="true" className="mr-1.5 h-4 w-4" />
+            )}
+            {isOpen ? 'Hide SEO analysis' : 'Show SEO analysis'}
+            <span className="sr-only">
+              {audit ? ` — currently scoring ${audit.score} out of 100.` : ''}
+            </span>
+          </Button>
+        </div>
+      </div>
+
+      {/*
+        `hidden` rather than a conditional render: the panel has to stay mounted
+        for the summary above to keep updating. Tailwind's `hidden` is
+        `display: none`, so a collapsed section costs no layout and the block
+        editor below it does not move.
+      */}
+      <div className={cn('border-t', !isOpen && 'hidden')} id={detailsId}>
+        <SeoAuditPanel
+          document={pageDocument}
+          isCortexAiActive={isCortexAiActive}
+          keyword={pageSeo.keyword}
+          metaDescription={pageSeo.snapshot.metaDescription}
+          metaTitle={pageSeo.snapshot.metaTitle}
+          onAuditChange={handleAuditChange}
+          onKeywordChange={pageSeo.setKeyword}
+          scope="page"
+        />
+      </div>
+    </section>
+  );
+}
+
+export default PageSeoAuditSection;