create-nextblock 0.14.5 → 0.15.0

package/templates/nextblock-template/components/SiteScripts.tsx

@@ -0,0 +1,56 @@
+/*
+ * The loading behaviour of an external script is the admin's choice, stored per row
+ * as `load_strategy` (default / defer / async). A blocking load is sometimes the
+ * required one — anti-flicker snippets and consent gates have to run before render —
+ * so this file renders what was asked for instead of forcing `defer` on everything.
+ */
+/* eslint-disable @next/next/no-sync-scripts */
+import React from 'react';
+
+import { escapeInlineScript, type SiteScript, type SiteScriptPlacement } from '../lib/site-scripts/types';
+
+interface SiteScriptsProps {
+  nonce: string;
+  placement: SiteScriptPlacement;
+  scripts: SiteScript[];
+}
+
+/**
+ * Render the admin-authored site scripts for one injection point.
+ *
+ * Emitted as plain <script> elements rather than next/script: these are arbitrary
+ * author-supplied snippets that frequently expect to run at a specific position in
+ * the document, and next/script's strategies would relocate them. The CSP nonce is
+ * applied here so the snippets satisfy the policy without it needing 'unsafe-inline'.
+ */
+export default function SiteScripts({ nonce, placement, scripts }: SiteScriptsProps) {
+  const forPlacement = scripts.filter((script) => script.placement === placement);
+
+  if (forPlacement.length === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {forPlacement.map((script) =>
+        script.src ? (
+          <script
+            key={script.id}
+            src={script.src}
+            nonce={nonce || undefined}
+            {...(script.load_strategy === 'async' ? { async: true } : {})}
+            {...(script.load_strategy === 'defer' ? { defer: true } : {})}
+            data-nb-script={script.id}
+          />
+        ) : (
+          <script
+            key={script.id}
+            nonce={nonce || undefined}
+            data-nb-script={script.id}
+            dangerouslySetInnerHTML={{ __html: escapeInlineScript(script.code) }}
+          />
+        )
+      )}
+    </>
+  );
+}

package/templates/nextblock-template/components/blocks/renderers/TextBlockRenderer.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import { headers } from 'next/headers';
 import ClientTextBlockRenderer from "./ClientTextBlockRenderer";
 import type { VisualEditAttributes } from "../../../lib/visual-editing/types";
+import { addNonceToInlineScripts } from "../../../lib/blocks/inlineScriptNonce";
 import { substitutePrivacyMergeTags } from "../../../lib/privacy/contact-emails";
 
 export type TextBlockContent = {
@@ -15,15 +16,6 @@ interface TextBlockRendererProps {
   renderContext?: 'prose' | 'section';
 }
 
-function addNonceToInlineScripts(html: string, nonce: string): string {
-  if (!html || !nonce) return html || '';
-  // Add nonce to <script> tags that do not already have a nonce
-  // and do not have a src attribute (inline scripts)
-  return html.replace(/<script(?![^>]*\bsrc=)([^>]*)(?<!nonce=["'][^"']*["'])>/gi, (_m, attrs) => {
-    return `<script nonce="${nonce}"${attrs}>`;
-  });
-}
-
 const TextBlockRenderer: React.FC<TextBlockRendererProps> = async ({
   content,
   languageId,

package/templates/nextblock-template/docs/04-DATABASE-AND-AUTH.md

@@ -198,7 +198,13 @@ production or shared database change.
   `libs/db/src/supabase/migrations` for each new schema/data change.
 - Keep migrations non-destructive by default. Avoid dropping or rewriting data
   that may include orders, users, payments, or customer records.
-- Run `npm run db:migrate:check` before `npm run db:migrate`.
+- Run `npm run db:migrate:check` before `npm run db:migrate`. **Read its pending
+  list** — do not just look for a success line. If you added a migration and the
+  check reports `Pending: 0`, that file will never run (see below).
+- **Supabase matches migration history by version only, never by content.** A file
+  whose 14-digit version is already recorded remotely is skipped in silence — no
+  error, no output. That is why the check prints the pending list and warns when a
+  version is recorded remotely with no local file behind it.
 - If an existing database lists old baseline files such as
   `00000000000000_baseline_schema.sql` as pending, do not replay them. Use
   `npm run db:migrate:repair-history:check`, then
@@ -207,6 +213,30 @@ production or shared database change.
   rerun `npm run db:migrate:check`.
 - Use `npm run db:migrate:fresh` only for a brand-new empty database.
 
+#### Why `db:migrate:check` is read-only by construction
+
+On 2026-08-10 the check applied migration `00000000000017` to the production
+project while printing `DRY RUN: migrations will *not* be pushed` and `Dry run
+complete. No database changes were applied.` The `--check` path then ran
+`supabase link --yes` followed by `supabase db push --dry-run` (Supabase CLI
+v2.107); which of the two executed the SQL was never established, and the decisive
+probe would have written a row to the production migration history.
+
+`tools/scripts/push-db-migrations.js` no longer runs either on the check path. It
+now runs only `supabase migration list` — a pure read — and derives the pending set
+by diffing local files against remote history. Consequences worth keeping:
+
+- The check links nothing. An unlinked repo is told to run `supabase link` itself
+  rather than having project state written underneath a command called "check".
+- The check needs no `SUPABASE_ACCESS_TOKEN`, because only linking did.
+- The apply path derives its baseline-replay guard from the same read instead of
+  regex-scraping `db push --dry-run` output, and returns early when nothing is
+  pending, so `db push` is never invoked without work to do.
+- `parseMigrationList` is unit-tested in `tools/scripts/push-db-migrations.test.ts`.
+
+If a future CLI upgrade tempts you back toward `db push --dry-run` for previewing:
+don't. A command named `check` must not be able to write.
+
 ### Category map
 
 | Migration file | Domain | What it covers |

package/templates/nextblock-template/docs/08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md

@@ -1060,6 +1060,157 @@ Unsplash has strict usage rules; Pexels' license is permissive (attribution opti
 - `importExternalImageToMedia` (`apps/nextblock/app/cms/media/import-external-image.ts`, ADMIN/WRITER) downloads an external image (SSRF-guarded, 15MB/15s caps), measures it with `sharp`, generates a blur placeholder, uploads to R2/Supabase Storage via the shared storage provider, and records it with `recordMediaUpload`. Returns `{ media_id, object_key, width, height, url, blur_data_url }`.
 - Editor UX: `ImageBlockEditor` and `BackgroundSelector` accept a pasted image URL and show a **Save to media library** action that swaps the external URL for a permanent optimized media reference (or the author can replace it with their own uploaded asset).
 
+## MCP Server (external client access)
+
+Cortex AI is dual-access. Alongside the in-app BYOK path (dashboard chat + inline
+editor), the same tool registry is exposed over the **Model Context Protocol** at
+`/api/mcp`, so Claude Code, Claude Desktop, Cursor, and VS Code can operate the CMS
+from inside the editor.
+
+### Files
+
+| File | Purpose |
+| --- | --- |
+| `libs/cortex/src/lib/mcp-server.ts` | Transport-agnostic JSON-RPC 2.0 engine. No `next` imports, so it is unit-testable. |
+| `libs/cortex/src/lib/mcp-tool-registry.ts` | Zod→JSON Schema conversion, read/write scope table, MCP-contract aliases, tool dispatch, resources, prompts. |
+| `libs/cortex/src/lib/mcp-tokens.ts` | Token mint/hash/verify, MCP settings resolver, localhost-trust rules. |
+| `libs/cortex/src/lib/mcp-server.test.ts` | 33 tests across tokens, registry, and protocol. |
+| `apps/nextblock/app/api/mcp/route.ts` | Streamable HTTP shim + hybrid auth + tool-context construction. |
+| `apps/nextblock/app/cms/settings/cortex-ai/mcp-actions.ts` | Admin server actions: settings, mint, revoke. |
+| `apps/nextblock/app/cms/settings/cortex-ai/McpServerSettingsCard.tsx` | Settings UI + copy-paste client config. |
+| `apps/nextblock/app/cms/settings/cortex-ai/require-admin.ts` | Shared admin gate (also used by `actions.ts`). |
+| `libs/db/src/supabase/migrations/00000000000017_cortex_ai_mcp_server.sql` | `mcp_access_tokens` table + `cortex_ai_mcp_settings` RLS. |
+
+### Protocol decisions
+
+**Hand-rolled, not `@modelcontextprotocol/sdk`.** The needed surface (initialize,
+tools/list, tools/call, resources/*, prompts/*, ping) is small and declarative. The v1
+SDK pulls in `express`, `cors`, `hono`, and `@hono/node-server` — heavy transitive
+weight for a publishable lib whose only peer dependency is `next` — and its default
+`StreamableHTTPServerTransport` is built on Node `IncomingMessage`/`ServerResponse`
+rather than the Web `Request`/`Response` an App Router handler receives.
+
+**Dual-era.** The spec forked: `2026-07-28` is stateless (no `initialize`, no session
+id, protocol metadata in a per-request `_meta` envelope), while everything through
+`2025-11-25` is handshake-based. As of 2026-08 every shipping client is legacy-era, so
+that path must work; the modern path is detected and served too. Because the server is
+stateless either way, supporting both costs nothing.
+
+Deliberate behaviours, each of which breaks a real client if changed:
+
+- **Notifications get `202 Accepted` with an empty body.** Returning a JSON-RPC
+  envelope for a message with no `id` desyncs strict clients.
+- **GET returns `405`.** The server never initiates requests or pushes unsolicited
+  notifications, so there is no stream to open. The spec explicitly allows 405 here.
+- **401 carries a bare `WWW-Authenticate: Bearer`.** Adding a `resource_metadata`
+  parameter (or serving `/.well-known/oauth-protected-resource`) advertises RFC 9728
+  OAuth discovery, and Claude Code responds by starting an OAuth flow that dead-ends
+  against a static-token server.
+- **Tool failures are `isError: true` on a *successful* result**, not JSON-RPC errors.
+  Only unknown-tool and scope denial use the error channel, because those are the
+  faults a model cannot fix by retrying with different arguments.
+- **`inputSchema` is always a JSON Schema object** with `$schema` stripped (MCP defines
+  the dialect; some clients reject the extra key). Converted with `io: 'input'` so
+  `.default()` fields stay optional.
+- **Array bodies are rejected.** JSON-RPC batching was removed in `2025-06-18`.
+- **`Origin` is validated when present** (DNS-rebinding defence, a spec MUST) and
+  answered with 403. Native clients send no Origin, so absence is allowed.
+
+### Authentication
+
+Three accepted paths, in priority order, all gated behind
+`verifyPackageOnline('cortex-ai')` and the `enabled` setting:
+
+1. **Bearer token** from `public.mcp_access_tokens` — what every external client uses.
+2. **Authenticated ADMIN cookie session** — lets the dashboard reach the endpoint
+   without minting a token.
+3. **Loopback in development** — only when `allowLocalhostWithoutToken` is on *and*
+   `NODE_ENV !== 'production'`. Behind a proxy the `Host` header is attacker-
+   controllable, so localhost trust is a development affordance only.
+
+Tokens are stored as **SHA-256 hashes**; the plaintext (`nbmcp_` + 256 bits base64url)
+is shown once at mint time and is unrecoverable. This differs from the OpenRouter BYOK
+key on purpose: that key must be handed back to OpenRouter, so it needs a reversible
+envelope, whereas an MCP token only ever needs to be *compared*. `token_prefix` is a
+non-secret display fragment. Revocation is a tombstone (`revoked_at`), which keeps the
+hash in the unique index so the same value can never be re-minted.
+
+The minted token is returned through a **server action return value**, never a redirect
+query string — a `?success=<token>` would land in browser history, the referrer header,
+and the server access log.
+
+### Scopes
+
+`CORTEX_MCP_TOOL_KINDS` classifies all 29 registry tools as `read` or `write`. A
+read-only token does not merely get refused on a write — the mutating tools are absent
+from its `tools/list` entirely, aliases included.
+
+The table is **exhaustive by construction**: `assertCortexMcpToolCoverage` compares its
+keys against the live factory output, and a unit test fails if they diverge. An
+unclassified tool is *withheld*, never defaulted to `read`, so adding a tool to the
+agent without classifying it is a loud failure rather than a silent hole.
+
+### Confirmation is skipped over MCP
+
+The in-app two-phase confirm matches a phrase in the user's *next chat message*, which
+has no analogue in MCP — there is no channel to carry a human phrase back between a
+tool call and its result. Every MCP host already gates tool calls behind its own
+approval UI, so leaving it on would just make every mutating tool return a preview
+forever. The real control is the token scope. `ToolExecutionContext.skipConfirmation`
+is therefore `true` for all MCP calls.
+
+### MCP-contract tool names
+
+Five names are exposed as aliases forwarding to existing executors, so external clients
+get the documented contract without forking tested code. The canonical names remain
+listed too, and each alias description begins with "Alias of `<canonical>`" so a model
+does not call both.
+
+| MCP name | Forwards to |
+| --- | --- |
+| `get_database_schema` | `describe_database_schema` |
+| `generate_jsonb_layout` | `rewrite_page_draft` (stages a Live Draft; nothing goes live unpublished) |
+| `query_site_analytics` | `fetch_ecommerce_stats` |
+| `update_site_navigation` | `update_navigation_bar` |
+| `search_stock_media` | `search_stock_photos` |
+
+### Resources and prompts
+
+Resources: `cortex://schema/database`, `cortex://schema/blocks`,
+`cortex://schema/custom-blocks`. Prompts: `build-page`, `clone-from-url`,
+`translate-content`.
+
+### Settings and client configuration
+
+`/cms/settings/cortex-ai` gains an "MCP server access" card: enable/disable, localhost
+trust, token mint/revoke, and copy-paste config for all four clients. **The server is
+disabled by default** — it is a remote write surface onto live content, so it must be
+an explicit opt-in.
+
+Client config differs in ways that silently no-op if copied wrong, which is why the UI
+generates each one rather than documenting a single snippet:
+
+- **Claude Code** — `mcpServers`, and `"type": "http"` is *required* (a `url` with no
+  `type` is a hard error that skips the server).
+- **Cursor** — `mcpServers`, infers transport from `url`, no `type` needed.
+- **VS Code** — top-level `servers`, **not** `mcpServers`, and prompts for the token
+  via `inputs` rather than storing it.
+- **Claude Desktop** — `claude_desktop_config.json` is stdio-only, so a remote server
+  needs either the Connectors UI (which dials out from Anthropic's cloud, so localhost
+  and firewalled sites will not connect) or the `mcp-remote` stdio bridge.
+
+### Related hardening
+
+`read_database_records` previously filtered only `cortex_ai_openrouter_api_key` from
+`site_settings`. The `isSensitiveKey` heuristic inspects *column names*, and a
+site_settings row is `{ key, value }` — neither name trips it, so the stock-photo and
+payment/email secret rows passed through. That was low-risk while the tool was
+dashboard-only; exposing it to remote MCP clients widened it. `ai-global-agent-db-tools.ts`
+now carries `PROTECTED_SITE_SETTING_KEYS`, redacted on read and refused on write.
+
+`mcp_access_tokens` is deliberately **absent** from `tableConfigs`, so the generic DB
+tools cannot read token hashes or insert rows.
+
 ## Advanced Agent Settings
 
 The global agent's model limits are admin-tunable from `/cms/settings/cortex-ai` (collapsible "Advanced settings"), stored as a non-secret JSON `site_settings` row `cortex_ai_agent_settings` and read by the route via `resolveCortexAiAgentSettings(supabase)` (defaults + clamping in `normalizeCortexAiAgentSettings`, `libs/cortex/src/lib/ai-config.ts`):
@@ -1405,3 +1556,124 @@ When modifying Cortex AI, keep these invariants:
 11. If a side-effecting tool succeeds and the model fails afterward, report the tool result instead of retrying blindly.
 12. Free OpenRouter models are useful but unstable; guard against 429s, malformed tool-call text, invalid HTML fragments, and no-output generation.
 13. Multilingual mutations should use active rows from `languages`, not hardcoded assumptions.
+14. MCP runs with the service-role client, so RLS is not an authorization boundary
+    there. Privileged tools re-check the actor's CMS role themselves.
+15. A substituted actor identity is for attribution only, never authorization.
+16. The audit log for site scripts is append-only in the database. Reverting writes a
+    new revision; it never removes one.
+17. Inline scripts in block HTML need the CSP nonce, and must wait for hydration
+    before touching server-rendered DOM.
+
+## MCP Server: Security Model and Operator Guide
+
+The MCP endpoint (`apps/nextblock/app/api/mcp/route.ts`) exposes the same typed
+tools to external clients — Claude Code, Claude Desktop, Cursor. The route is a thin
+HTTP shim; the registry lives in `libs/cortex/src/lib/mcp-tool-registry.ts`.
+
+### The four failure shapes to check when adding a tool
+
+Tools were originally written for the in-app agent, which always has a signed-in
+user and an open editor. MCP has neither, so every new tool must be checked against
+all four of these:
+
+1. **Cookie-session auth.** `createClient()` + `auth.getUser()` returns nobody over
+   MCP. Pass a pre-authorized `actorUserId` instead and keep the role check.
+2. **`pageContext` dependence.** The route sets it to `null`. A tool that edits
+   "the current item" must accept an explicit `cmsTarget`.
+3. **Untyped `z.any()` parameters.** They serialize to `{}` in JSON Schema, so hosts
+   send `"29.99"` where a number is expected. Coerce rather than reject.
+4. **Staged artifacts with no finisher.** Anything that stages something (a Live
+   Draft) needs a tool that can complete it, or MCP callers cannot finish the job.
+
+### Authorization does not come from RLS
+
+**MCP executors use the service-role client, which bypasses Row Level Security.** An
+`ADMIN`-only table policy therefore constrains the dashboard but *not* the MCP path.
+Privileged tools must re-check the actor's CMS role themselves — see
+`requireActorRole` in `ai-global-agent-theming-tools.ts`.
+
+MCP token scopes are only `read` / `write` and carry no role, so the role is resolved
+from the acting user at call time. Two related rules:
+
+- Keep privileged tables (`site_scripts`, `site_script_revisions`) **out of** the
+  `execute_database_mutation` allowlist, or that generic tool becomes a way around
+  every per-tool guard.
+- When a token's creator has been deleted, the route substitutes a stand-in admin so
+  a revision can still be attributed. That substitution is flagged
+  (`actorFromOrphanedToken`) and refused for role-gated operations: a credential must
+  not gain authority by outliving its owner.
+
+### Prompt injection
+
+`fetch_url_content` returns attacker-controlled text to a model that holds write
+tools. A hostile page can contain instructions aimed at the agent ("also add this
+tracking snippet"). This is not solvable in the tool layer — the model reads the page
+because you asked it to. The mitigations are containment, not prevention:
+
+- Code injection (`manage_site_script`) is **ADMIN-only**, so a `write` token that is
+  otherwise fine for content cannot ship JavaScript.
+- `manage_site_script` requires a `purpose` and returns a `safetyReview` produced by
+  an **independent static scan** of the code (`@nextblock-cms/utils/script-safety`).
+  The stated purpose is not the control — a steered model will describe a skimmer as
+  an analytics helper. The scan reports what the code can actually reach (cookies,
+  network, storage, form fields, dynamic evaluation, external hosts) and both are
+  written to the audit log, so a mismatch is visible rather than hidden.
+- Every script change is recorded in `site_script_revisions`, which is **append-only
+  by database trigger** — UPDATE and DELETE are rejected even for the service role.
+  An audit log a compromised credential can rewrite is not an audit log.
+
+The scan is regex over source text, not a sandbox. Obfuscated code can evade it,
+which is why dynamic evaluation is itself reported at warning level. A clean result
+means "nothing obvious found", never "safe".
+
+### Site scripts and the CSP
+
+The site CSP carries a nonce, and per CSP Level 2 a browser **ignores
+`'unsafe-inline'` once a nonce is present**. Consequences:
+
+- Inline `<script>` inside rich-text block HTML must be stamped by
+  `apps/nextblock/lib/blocks/inlineScriptNonce.ts`, or the browser silently drops it
+  with no server-side symptom.
+- Because NextBlock nonces author scripts, an external `src` on a site script is
+  authorized regardless of the CSP host allowlist. That is inherent to the feature
+  and a reason it is ADMIN-only.
+
+Author scripts must also not fight React hydration: a script that changes text,
+classes, or attributes of server-rendered markup before hydration makes the client
+disagree with the SSR HTML and React discards that subtree. Wrap DOM work as:
+
+```js
+function run() { /* ... */ }
+if (document.readyState === 'complete') run();
+else window.addEventListener('load', run);
+```
+
+### SSRF
+
+`fetch_url_content` and the media importer perform server-side HTTP on a
+caller-supplied URL, and `fetch_url_content` is a **read**-scoped tool — so its
+blocklist is what stops a read-only token from reaching internal services. The
+blocklist is duplicated (`isBlockedFetchHost` in cortex, `isBlockedImportHost` in the
+app) because a published lib cannot import from the app: **fix both together.**
+Regression tests live in `ai-global-agent-ssrf.test.ts`; IPv4-mapped IPv6
+(`::ffff:127.0.0.1`) previously bypassed both.
+
+### Building a whole site in one pass
+
+The tools below exist specifically so a site can be built without a human clicking
+through the dashboard. Rough order for a from-scratch build:
+
+| Step | Tools |
+| --- | --- |
+| Ground yourself | `get_database_schema`, `list_media`, `list_site_themes`, `list_product_categories` |
+| Brand it | `manage_site_theme`, `update_global_css` |
+| Assets | `search_stock_media`, `upload_media` |
+| Catalogue | `manage_product_category`, `create_cms_product`, `manage_product_variants` |
+| Pages | `generate_jsonb_layout` then `publish_content_draft` |
+| Navigation | `update_site_navigation`, `update_footer` |
+| Locales | `manage_language` then `translate_content_bulk` |
+| Motion | `update_global_css` plus `manage_site_script` |
+
+`manage_language` must run before any translation: `translate_page` and
+`translate_content_bulk` can only target a language that already exists and is
+active.

package/templates/nextblock-template/lib/blocks/inlineScriptNonce.ts

@@ -0,0 +1,20 @@
+/**
+ * Stamp the request's CSP nonce onto inline <script> tags inside block HTML.
+ *
+ * Rich-text blocks may legitimately carry an inline <script> (an editor or Cortex AI
+ * adding a small animation or widget). The site's CSP lists a nonce in `script-src`,
+ * and per CSP Level 2 a browser IGNORES `'unsafe-inline'` once a nonce or hash is
+ * present — so an un-nonced inline script is silently blocked, with no server-side
+ * symptom. Adding the nonce is what makes authored JS actually run.
+ *
+ * Only inline scripts are touched: a `src=` script loads a remote file and is
+ * governed by the host allowlist instead, and re-stamping one that already carries a
+ * nonce would corrupt it.
+ */
+export function addNonceToInlineScripts(html: string, nonce: string): string {
+  if (!html || !nonce) return html || '';
+
+  return html.replace(/<script(?![^>]*\bsrc=)([^>]*)(?<!nonce=["'][^"']*["'])>/gi, (_match, attrs) => {
+    return `<script nonce="${nonce}"${attrs}>`;
+  });
+}

package/templates/nextblock-template/lib/setup/migrations-bundle.ts

@@ -98,5 +98,10 @@ export const MIGRATIONS_BUNDLE: BundledMigration[] = [
     "version": "00000000000016",
     "name": "00000000000016_product_revisions_and_revision_baseline.sql",
     "sql": "-- 00000000000016_product_revisions_and_revision_baseline.sql\n--\n-- Revision History, part 1 of 2 (schema). The application-side rewrite lives in\n-- apps/nextblock/app/cms/revisions/**.\n--\n-- Three things happen here:\n--\n--   1. products.version    — the monotonic counter the hybrid revision engine drives,\n--                            mirroring pages.version / posts.version.\n--\n--   2. product_revisions   — a structural mirror of page_revisions / post_revisions.\n--                            product_id is uuid (products.id is uuid, not bigint), and\n--                            writes are gated on is_admin() to match products_*_policy\n--                            rather than the ADMIN|WRITER pattern the page/post revision\n--                            tables use. A WRITER who could insert a revision but not\n--                            apply a restore would get a silent no-op restore, because\n--                            PostgREST returns no error for an UPDATE matching zero rows.\n--\n--   3. Revision baseline   — every page, post and product gets a real `snapshot` row to\n--                            restore to. Until now the CMS synthesised a fake \"Initial\n--                            Version\" entry in the UI whose Restore button resolved to\n--                            \"current metadata + zero blocks\" and wiped the content.\n--                            There is now an actual stored baseline instead.\n--\n--                            Case A (version = 1, no revisions at all): the live row IS\n--                            version 1. This covers seeded content — 00000000000003\n--                            inserts every page and post at version 1 and writes no\n--                            revision rows — and everything authored since the CMS save\n--                            path stopped recording revisions. Snapshotting it at\n--                            version 1 is what makes \"restore the original seeded page\"\n--                            real for the first time.\n--\n--                            Case B (version > 1 but no snapshot at or below it): the\n--                            true v1 is unrecoverable and is NOT fabricated. A snapshot\n--                            of the current state is stored at the current version so the\n--                            diff chain has a valid base and future restores resolve.\n--\n-- Forward-only, idempotent, and it modifies no existing row: every backfill is an\n-- INSERT ... WHERE NOT EXISTS ... ON CONFLICT DO NOTHING.\n\n-- ---------------------------------------------------------------------------\n-- 1. products.version\n-- ---------------------------------------------------------------------------\n\nALTER TABLE public.products\n    ADD COLUMN IF NOT EXISTS version integer DEFAULT 1 NOT NULL;\n\nCOMMENT ON COLUMN public.products.version IS 'Monotonic version number for hybrid revisions.';\n\n-- ---------------------------------------------------------------------------\n-- 2. product_revisions\n-- ---------------------------------------------------------------------------\n\nCREATE TABLE IF NOT EXISTS public.product_revisions (\n    id bigint NOT NULL,\n    product_id uuid NOT NULL,\n    author_id uuid,\n    version integer NOT NULL,\n    revision_type public.revision_type NOT NULL,\n    content jsonb NOT NULL,\n    created_at timestamp with time zone DEFAULT now() NOT NULL\n);\n\nCOMMENT ON TABLE public.product_revisions IS 'Hybrid (snapshot/diff) revisions for products.';\nCOMMENT ON COLUMN public.product_revisions.content IS 'If snapshot: full content; if diff: JSON Patch array.';\n\nDO $rb$\nBEGIN\n  IF NOT EXISTS (\n    SELECT 1 FROM pg_attribute\n     WHERE attrelid = 'public.product_revisions'::regclass\n       AND attname  = 'id'\n       AND attidentity <> ''\n  ) THEN\n    ALTER TABLE public.product_revisions\n      ALTER COLUMN id ADD GENERATED BY DEFAULT AS IDENTITY (\n        SEQUENCE NAME public.product_revisions_id_seq\n        START WITH 1\n        INCREMENT BY 1\n        NO MINVALUE\n        NO MAXVALUE\n        CACHE 1\n      );\n  END IF;\nEND $rb$;\n\nDO $rb$\nBEGIN\n  IF NOT EXISTS (SELECT 1 FROM pg_constraint\n                  WHERE conname = 'product_revisions_pkey'\n                    AND conrelid = 'public.product_revisions'::regclass) THEN\n    ALTER TABLE ONLY public.product_revisions\n      ADD CONSTRAINT product_revisions_pkey PRIMARY KEY (id);\n  END IF;\nEND $rb$;\n\nDO $rb$\nBEGIN\n  IF NOT EXISTS (SELECT 1 FROM pg_constraint\n                  WHERE conname = 'product_revisions_product_version_key'\n                    AND conrelid = 'public.product_revisions'::regclass) THEN\n    ALTER TABLE ONLY public.product_revisions\n      ADD CONSTRAINT product_revisions_product_version_key UNIQUE (product_id, version);\n  END IF;\nEND $rb$;\n\nDO $rb$\nBEGIN\n  IF NOT EXISTS (SELECT 1 FROM pg_constraint\n                  WHERE conname = 'product_revisions_author_id_fkey'\n                    AND conrelid = 'public.product_revisions'::regclass) THEN\n    ALTER TABLE ONLY public.product_revisions\n      ADD CONSTRAINT product_revisions_author_id_fkey\n      FOREIGN KEY (author_id) REFERENCES public.profiles(id) ON DELETE SET NULL;\n  END IF;\nEND $rb$;\n\nDO $rb$\nBEGIN\n  IF NOT EXISTS (SELECT 1 FROM pg_constraint\n                  WHERE conname = 'product_revisions_product_id_fkey'\n                    AND conrelid = 'public.product_revisions'::regclass) THEN\n    ALTER TABLE ONLY public.product_revisions\n      ADD CONSTRAINT product_revisions_product_id_fkey\n      FOREIGN KEY (product_id) REFERENCES public.products(id) ON DELETE CASCADE;\n  END IF;\nEND $rb$;\n\nCREATE INDEX IF NOT EXISTS idx_product_revisions_author_id\n    ON public.product_revisions USING btree (author_id);\n\nCREATE INDEX IF NOT EXISTS idx_product_revisions_product_id_version\n    ON public.product_revisions USING btree (product_id, version);\n\nALTER TABLE public.product_revisions ENABLE ROW LEVEL SECURITY;\n\nDROP POLICY IF EXISTS product_revisions_read_policy ON public.product_revisions;\nCREATE POLICY product_revisions_read_policy ON public.product_revisions\n  FOR SELECT TO authenticated USING (true);\n\nDROP POLICY IF EXISTS product_revisions_insert_policy ON public.product_revisions;\nCREATE POLICY product_revisions_insert_policy ON public.product_revisions\n  FOR INSERT TO authenticated\n  WITH CHECK (((SELECT public.is_admin() AS is_admin) IS TRUE));\n\nDROP POLICY IF EXISTS product_revisions_update_policy ON public.product_revisions;\nCREATE POLICY product_revisions_update_policy ON public.product_revisions\n  FOR UPDATE TO authenticated\n  USING (((SELECT public.is_admin() AS is_admin) IS TRUE))\n  WITH CHECK (((SELECT public.is_admin() AS is_admin) IS TRUE));\n\nDROP POLICY IF EXISTS product_revisions_delete_policy ON public.product_revisions;\nCREATE POLICY product_revisions_delete_policy ON public.product_revisions\n  FOR DELETE TO authenticated\n  USING (((SELECT public.is_admin() AS is_admin) IS TRUE));\n\nGRANT ALL ON TABLE    public.product_revisions        TO anon;\nGRANT ALL ON TABLE    public.product_revisions        TO authenticated;\nGRANT ALL ON TABLE    public.product_revisions        TO service_role;\nGRANT ALL ON SEQUENCE public.product_revisions_id_seq TO anon;\nGRANT ALL ON SEQUENCE public.product_revisions_id_seq TO authenticated;\nGRANT ALL ON SEQUENCE public.product_revisions_id_seq TO service_role;\n\n-- ---------------------------------------------------------------------------\n-- 3. Revision baseline backfill\n--\n-- The JSON shape must match FullPageContent / FullPostContent / FullProductContent\n-- in apps/nextblock/app/cms/revisions/utils.ts exactly, or the first diff taken\n-- against a baseline row will be full of phantom operations.\n--\n-- Timestamps are rendered with an explicit millisecond-precision UTC format so they\n-- match JavaScript's Date#toISOString() (\"2026-07-03T17:52:15.643Z\"). Postgres'\n-- default jsonb rendering of timestamptz (\"2026-07-03T17:52:15.643901+00:00\") would\n-- differ from the value the application writes and produce a spurious diff on the\n-- very next save.\n-- ---------------------------------------------------------------------------\n\n-- 3a. Pages\nINSERT INTO public.page_revisions (page_id, author_id, version, revision_type, content)\nSELECT\n    p.id,\n    NULL::uuid,\n    p.version,\n    'snapshot'::public.revision_type,\n    jsonb_build_object(\n      'meta', jsonb_build_object(\n        'title',            p.title,\n        'slug',             p.slug,\n        'language_id',      p.language_id,\n        'status',           p.status,\n        'meta_title',       p.meta_title,\n        'meta_description', p.meta_description,\n        'custom_canonical', p.custom_canonical,\n        'published_at',     to_char(p.published_at AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"'),\n        'feature_image_id', p.feature_image_id\n      ),\n      'blocks', COALESCE((\n        SELECT jsonb_agg(\n                 jsonb_build_object(\n                   'language_id', b.language_id,\n                   'block_type',  b.block_type,\n                   'content',     b.content,\n                   'order',       b.\"order\"\n                 ) ORDER BY b.\"order\" ASC, b.id ASC\n               )\n          FROM public.blocks b\n         WHERE b.page_id = p.id\n      ), '[]'::jsonb)\n    )\n  FROM public.pages p\n WHERE NOT EXISTS (\n         SELECT 1 FROM public.page_revisions r\n          WHERE r.page_id = p.id\n            AND r.revision_type = 'snapshot'\n            AND r.version <= p.version\n       )\nON CONFLICT (page_id, version) DO NOTHING;\n\n-- 3b. Posts\nINSERT INTO public.post_revisions (post_id, author_id, version, revision_type, content)\nSELECT\n    po.id,\n    NULL::uuid,\n    po.version,\n    'snapshot'::public.revision_type,\n    jsonb_build_object(\n      'meta', jsonb_build_object(\n        'title',            po.title,\n        'slug',             po.slug,\n        'language_id',      po.language_id,\n        'status',           po.status,\n        'meta_title',       po.meta_title,\n        'meta_description', po.meta_description,\n        'custom_canonical', po.custom_canonical,\n        'published_at',     to_char(po.published_at AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"'),\n        'feature_image_id', po.feature_image_id,\n        'label',            po.label,\n        'excerpt',          po.excerpt,\n        'subtitle',         po.subtitle\n      ),\n      'blocks', COALESCE((\n        SELECT jsonb_agg(\n                 jsonb_build_object(\n                   'language_id', b.language_id,\n                   'block_type',  b.block_type,\n                   'content',     b.content,\n                   'order',       b.\"order\"\n                 ) ORDER BY b.\"order\" ASC, b.id ASC\n               )\n          FROM public.blocks b\n         WHERE b.post_id = po.id\n      ), '[]'::jsonb)\n    )\n  FROM public.posts po\n WHERE NOT EXISTS (\n         SELECT 1 FROM public.post_revisions r\n          WHERE r.post_id = po.id\n            AND r.revision_type = 'snapshot'\n            AND r.version <= po.version\n       )\nON CONFLICT (post_id, version) DO NOTHING;\n\n-- 3c. Products.\n--\n-- Content only. price/prices/sale_*/scheduled_*/stock/sku/average_rating/total_reviews\n-- are deliberately excluded from the snapshot: pricing and inventory are mutated from\n-- outside the editor (promotions, Freemius sync, order fulfilment), ratings are derived\n-- aggregates, and inventory_items is keyed by bare SKU text with no FK to products — so\n-- replaying commerce state on restore would reach rows the editor never touched.\n-- Restoring a product restores its content, not its commerce state.\nINSERT INTO public.product_revisions (product_id, author_id, version, revision_type, content)\nSELECT\n    pr.id,\n    NULL::uuid,\n    pr.version,\n    'snapshot'::public.revision_type,\n    jsonb_build_object(\n      'meta', jsonb_build_object(\n        'title',             pr.title,\n        'slug',              pr.slug,\n        'language_id',       pr.language_id,\n        'status',            pr.status,\n        'meta_title',        pr.meta_title,\n        'meta_description',  pr.meta_description,\n        'custom_canonical',  pr.custom_canonical,\n        'published_at',      to_char(pr.published_at AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.MS\"Z\"'),\n        'short_description', pr.short_description,\n        'description_json',  pr.description_json\n      ),\n      'blocks', COALESCE((\n        SELECT jsonb_agg(\n                 jsonb_build_object(\n                   'language_id', b.language_id,\n                   'block_type',  b.block_type,\n                   'content',     b.content,\n                   'order',       b.\"order\"\n                 ) ORDER BY b.\"order\" ASC, b.id ASC\n               )\n          FROM public.blocks b\n         WHERE b.product_id = pr.id\n      ), '[]'::jsonb)\n    )\n  FROM public.products pr\n WHERE NOT EXISTS (\n         SELECT 1 FROM public.product_revisions r\n          WHERE r.product_id = pr.id\n            AND r.revision_type = 'snapshot'\n            AND r.version <= pr.version\n       )\nON CONFLICT (product_id, version) DO NOTHING;\n"
+  },
+  {
+    "version": "00000000000017",
+    "name": "00000000000017_cortex_ai_mcp_server.sql",
+    "sql": "-- Cortex AI MCP (Model Context Protocol) server access.\n--\n-- Adds the bearer-token store that gates /api/mcp, the endpoint that exposes the\n-- Cortex AI tool registry to external MCP clients (Claude Code, Claude Desktop,\n-- Cursor, VS Code). Two pieces:\n--\n--   1. public.mcp_access_tokens — one row per issued token. We store ONLY the\n--      SHA-256 hash of the token, never the token itself: the plaintext is shown\n--      to the admin exactly once at mint time and is unrecoverable afterwards, so\n--      a database leak cannot be replayed against the MCP endpoint. `token_prefix`\n--      is the non-secret leading fragment kept purely so the UI can tell two tokens\n--      apart in a list.\n--\n--   2. cortex_ai_mcp_settings — a non-secret JSON site_settings row holding the\n--      server on/off switch and the localhost-trust flag. It is added to all four\n--      site_settings policies so only authenticated ADMINs can read or write it;\n--      the MCP route itself reads it through the service-role client, which\n--      bypasses RLS.\n--\n-- Forward-only. Recreates the four site_settings policies idempotently, preserving\n-- every key already in each policy's sensitive array (note that\n-- language_detection_settings stays anon-READABLE and so is absent from the SELECT\n-- policy, exactly as migration 00000000000012 left it).\n\nCREATE TABLE IF NOT EXISTS public.mcp_access_tokens (\n  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  name text NOT NULL,\n  -- Lowercase hex SHA-256 of the plaintext token. Unique so a lookup is a single\n  -- indexed equality probe and duplicate mints are impossible.\n  token_hash text NOT NULL UNIQUE,\n  -- Non-secret display fragment, e.g. \"nbmcp_a1b2c3d4\". Never enough to authenticate.\n  token_prefix text NOT NULL,\n  -- 'read' grants the read-only tools; 'write' additionally grants the mutating ones.\n  scopes text[] NOT NULL DEFAULT ARRAY['read', 'write']::text[],\n  created_by uuid REFERENCES auth.users (id) ON DELETE SET NULL,\n  created_at timestamptz NOT NULL DEFAULT now(),\n  last_used_at timestamptz,\n  expires_at timestamptz,\n  revoked_at timestamptz\n);\n\nCOMMENT ON TABLE public.mcp_access_tokens IS\n  'Bearer tokens for the Cortex AI MCP server at /api/mcp. Stores SHA-256 hashes only; plaintext is displayed once at mint time.';\n\nCREATE INDEX IF NOT EXISTS mcp_access_tokens_token_hash_idx\n  ON public.mcp_access_tokens (token_hash);\n\n-- Orders the admin token list newest-first without a sort.\nCREATE INDEX IF NOT EXISTS mcp_access_tokens_created_at_idx\n  ON public.mcp_access_tokens (created_at DESC);\n\nALTER TABLE public.mcp_access_tokens ENABLE ROW LEVEL SECURITY;\n\n-- Tokens are credentials: admin-only, with no anon or WRITER access at all. The\n-- MCP route verifies them with the service-role client, which bypasses RLS.\nDROP POLICY IF EXISTS mcp_access_tokens_admin_select ON public.mcp_access_tokens;\nCREATE POLICY mcp_access_tokens_admin_select ON public.mcp_access_tokens\n  FOR SELECT TO authenticated\n  USING ((SELECT public.get_current_user_role()) = 'ADMIN'::public.user_role);\n\nDROP POLICY IF EXISTS mcp_access_tokens_admin_insert ON public.mcp_access_tokens;\nCREATE POLICY mcp_access_tokens_admin_insert ON public.mcp_access_tokens\n  FOR INSERT TO authenticated\n  WITH CHECK ((SELECT public.get_current_user_role()) = 'ADMIN'::public.user_role);\n\nDROP POLICY IF EXISTS mcp_access_tokens_admin_update ON public.mcp_access_tokens;\nCREATE POLICY mcp_access_tokens_admin_update ON public.mcp_access_tokens\n  FOR UPDATE TO authenticated\n  USING ((SELECT public.get_current_user_role()) = 'ADMIN'::public.user_role)\n  WITH CHECK ((SELECT public.get_current_user_role()) = 'ADMIN'::public.user_role);\n\nDROP POLICY IF EXISTS mcp_access_tokens_admin_delete ON public.mcp_access_tokens;\nCREATE POLICY mcp_access_tokens_admin_delete ON public.mcp_access_tokens\n  FOR DELETE TO authenticated\n  USING ((SELECT public.get_current_user_role()) = 'ADMIN'::public.user_role);\n\nGRANT SELECT, INSERT, UPDATE, DELETE ON public.mcp_access_tokens TO authenticated;\nGRANT ALL ON public.mcp_access_tokens TO service_role;\n\n-- Add cortex_ai_mcp_settings to the admin-only site_settings group (all four policies).\nDROP POLICY IF EXISTS site_settings_read_policy ON public.site_settings;\nCREATE POLICY site_settings_read_policy ON public.site_settings FOR SELECT USING (((key <> ALL (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) OR ((key = ANY (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT auth.role() AS role) = 'authenticated'::text) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = 'ADMIN'::public.user_role))));\n\nDROP POLICY IF EXISTS site_settings_insert_policy ON public.site_settings;\nCREATE POLICY site_settings_insert_policy ON public.site_settings FOR INSERT TO authenticated WITH CHECK ((((key <> ALL (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = ANY (ARRAY['ADMIN'::public.user_role, 'WRITER'::public.user_role]))) OR ((key = ANY (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = 'ADMIN'::public.user_role))));\n\nDROP POLICY IF EXISTS site_settings_update_policy ON public.site_settings;\nCREATE POLICY site_settings_update_policy ON public.site_settings FOR UPDATE TO authenticated USING ((((key <> ALL (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = ANY (ARRAY['ADMIN'::public.user_role, 'WRITER'::public.user_role]))) OR ((key = ANY (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = 'ADMIN'::public.user_role)))) WITH CHECK ((((key <> ALL (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = ANY (ARRAY['ADMIN'::public.user_role, 'WRITER'::public.user_role]))) OR ((key = ANY (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = 'ADMIN'::public.user_role))));\n\nDROP POLICY IF EXISTS site_settings_delete_policy ON public.site_settings;\nCREATE POLICY site_settings_delete_policy ON public.site_settings FOR DELETE TO authenticated USING ((((key <> ALL (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = ANY (ARRAY['ADMIN'::public.user_role, 'WRITER'::public.user_role]))) OR ((key = ANY (ARRAY['cortex_ai_openrouter_api_key'::text, 'bot_protection_secret'::text, 'email_secret'::text, 'payment_secret'::text, 'language_detection_settings'::text, 'cortex_ai_pexels_api_key'::text, 'cortex_ai_unsplash_access_key'::text, 'cortex_ai_mcp_settings'::text])) AND (( SELECT public.get_current_user_role() AS get_current_user_role) = 'ADMIN'::public.user_role))));\n"
   }
 ];

package/templates/nextblock-template/lib/site-scripts/revisions.ts

@@ -0,0 +1,71 @@
+import type { SiteScript } from './types';
+
+export type SiteScriptRevisionType = 'create' | 'update' | 'delete' | 'revert';
+export type SiteScriptRevisionSource = 'cms' | 'mcp';
+
+export interface SiteScriptRevision {
+  id: string;
+  script_id: string | null;
+  script_name: string;
+  revision_type: SiteScriptRevisionType;
+  actor_user_id: string | null;
+  source: SiteScriptRevisionSource;
+  summary: string | null;
+  snapshot: SiteScriptSnapshot;
+  created_at: string;
+}
+
+/**
+ * The restorable state of a script.
+ *
+ * Deliberately excludes `id`, `created_at`, and `updated_at`: restoring a revision
+ * writes these fields onto the live row (or recreates it), and carrying identity or
+ * timestamps across would either clash with the existing row or fake its history.
+ */
+export interface SiteScriptSnapshot {
+  name: string;
+  description: string | null;
+  code: string;
+  src: string | null;
+  placement: string;
+  load_strategy: string;
+  is_active: boolean;
+  sort_order: number;
+}
+
+export const SITE_SCRIPT_REVISION_COLUMNS =
+  'id, script_id, script_name, revision_type, actor_user_id, source, summary, snapshot, created_at';
+
+/** Normalise a script row, a partial payload, or an existing snapshot into a snapshot. */
+export function buildSiteScriptSnapshot(
+  row: Partial<SiteScript> | SiteScriptSnapshot | Record<string, unknown>
+): SiteScriptSnapshot {
+  const value = row as Record<string, unknown>;
+
+  return {
+    code: typeof value['code'] === 'string' ? value['code'] : '',
+    description: typeof value['description'] === 'string' ? value['description'] : null,
+    is_active: Boolean(value['is_active']),
+    load_strategy: typeof value['load_strategy'] === 'string' ? value['load_strategy'] : 'default',
+    name: typeof value['name'] === 'string' ? value['name'] : '',
+    placement: typeof value['placement'] === 'string' ? value['placement'] : 'body_end',
+    sort_order: Number.isFinite(value['sort_order']) ? Number(value['sort_order']) : 0,
+    src: typeof value['src'] === 'string' && value['src'] ? (value['src'] as string) : null,
+  };
+}
+
+/** One-line human description of what a revision did, shown in the history list. */
+export function describeSiteScriptRevision(revision: SiteScriptRevision): string {
+  if (revision.summary) return revision.summary;
+
+  switch (revision.revision_type) {
+    case 'create':
+      return `Created “${revision.script_name}”`;
+    case 'delete':
+      return `Deleted “${revision.script_name}”`;
+    case 'revert':
+      return `Restored “${revision.script_name}”`;
+    default:
+      return `Updated “${revision.script_name}”`;
+  }
+}

package/templates/nextblock-template/lib/site-scripts/types.ts

@@ -0,0 +1,46 @@
+/** Where a site script's tag is emitted in the document. */
+export type SiteScriptPlacement = 'head' | 'body_start' | 'body_end';
+
+/** Loading hint for external (`src`) scripts. Inline code ignores it. */
+export type SiteScriptLoadStrategy = 'default' | 'defer' | 'async';
+
+export interface SiteScript {
+  id: string;
+  name: string;
+  description: string | null;
+  /** Raw JS without the surrounding <script> tag. Ignored when `src` is set. */
+  code: string;
+  /** External script URL. Takes precedence over `code`. */
+  src: string | null;
+  placement: SiteScriptPlacement;
+  load_strategy: SiteScriptLoadStrategy;
+  is_active: boolean;
+  sort_order: number;
+}
+
+export const SITE_SCRIPT_PLACEMENTS: SiteScriptPlacement[] = ['head', 'body_start', 'body_end'];
+export const SITE_SCRIPT_LOAD_STRATEGIES: SiteScriptLoadStrategy[] = ['default', 'defer', 'async'];
+
+export const SITE_SCRIPT_COLUMNS =
+  'id, name, description, code, src, placement, load_strategy, is_active, sort_order';
+
+export function isSiteScriptPlacement(value: unknown): value is SiteScriptPlacement {
+  return typeof value === 'string' && (SITE_SCRIPT_PLACEMENTS as string[]).includes(value);
+}
+
+export function isSiteScriptLoadStrategy(value: unknown): value is SiteScriptLoadStrategy {
+  return typeof value === 'string' && (SITE_SCRIPT_LOAD_STRATEGIES as string[]).includes(value);
+}
+
+/**
+ * Guard against a script closing its own tag and escaping into markup.
+ *
+ * The code is emitted inside a <script> element, where the HTML parser ends the
+ * element at the first literal `</script`, regardless of JavaScript syntax — so a
+ * string containing it would terminate the script early and let whatever follows be
+ * parsed as HTML. Escaping the slash keeps the sequence inert to the parser while
+ * remaining the same string to JavaScript.
+ */
+export function escapeInlineScript(code: string): string {
+  return code.replace(/<\/(script)/gi, '<\\/$1');
+}

package/templates/nextblock-template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextblock-cms/template",
-  "version": "0.14.5",
+  "version": "0.15.0",
   "private": true,
   "scripts": {
     "dev": "next dev",