@riverbankcms/sdk 0.129.0 → 0.130.0

package/README.md

@@ -24,6 +24,20 @@ npm install @riverbankcms/sdk
 pnpm add @riverbankcms/sdk
 ```
 
+The SDK is the data-plane runtime only. It does not install or expose the
+`riverbankcms` command. SDK sites that use content/config management should
+declare the standalone CLI explicitly:
+
+```bash
+pnpm add @riverbankcms/sdk
+pnpm add -D riverbankcms
+pnpm exec riverbankcms --help
+```
+
+The CLI and SDK are versioned independently. Keep the CLI invocation project
+local (`pnpm exec`) so a site never depends on a transitive or globally
+installed binary.
+
 ## Quick Start
 
 > **Important:** The `baseUrl` parameter must be the complete API URL including the `/api` path. For example: `https://dashboard.example.com/api`
@@ -326,7 +340,7 @@ When a path might resolve to either a page or a content entry (blog post, produc
 ### Server-Side: loadContent
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 
 export default async function DynamicRoute({ params }) {
   const path = `/${params.slug?.join('/') || ''}`;
@@ -340,6 +354,9 @@ export default async function DynamicRoute({ params }) {
 
   // Pages get rendered with the Page component
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }
 
@@ -372,6 +389,7 @@ export function DynamicContent({ path }: { path: string }) {
   if (content.error) return <div>Error: {content.error.message}</div>;
 
   if (isPageContentResult(content)) {
+    if (!content.theme) return <div>This site needs a theme before it can be displayed.</div>;
     return <Page page={content.page} theme={content.theme} siteId={content.siteId} resolvedData={content.resolvedData} />;
   }
 
@@ -391,12 +409,15 @@ export function DynamicContent({ path }: { path: string }) {
 Route entries to different components based on their content type:
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 
 export default async function DynamicRoute({ params }) {
   const content = await loadContent({ client, siteId, path: `/${params.slug?.join('/') || ''}` });
 
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }
 
@@ -2657,7 +2678,9 @@ In this mode the SDK does not resolve, parse, normalize, or build tokens from th
 
 The optional theme-independent wrapper belongs inside `rendering`: use `runtime: { kind: 'responsive-only' }` (the default) for Riverbank's generated responsive utility scope, or `runtime: { kind: 'none' }` when the host owns that too. Do not combine override-only rendering with top-level `themeRuntime`, `theme`, `themes`, or `getTheme`. If you use SDK `Layout` directly, its header and footer must both be custom or disabled. Preview receives the same rendering selection and registry.
 
-The content response still carries a compatibility theme field for now; override-only rendering deliberately ignores it. Wire-level theme nullability is tracked separately in #1290.
+`SiteResponse.theme` is required but nullable: `Theme | null`. A null value means the CMS has no theme; it does not select a rendering mode. Override-only rendering deliberately ignores it. Themed catch-all rendering first prefers explicit `theme`, `themes`, or `getTheme` inputs, then uses the CMS theme. If none resolves, it throws the exported `MissingSdkThemeError` with code `missing_sdk_theme` before theme parsing or token construction.
+
+The nullable contract must be published before the server stops supplying its temporary fallback. Externally pinned hosts must upgrade to this SDK contract and either opt into override-only rendering or provide a real local/CMS theme before that server cutover.
 
 Keep the `server-only` marker at the top of the registry so Next.js turns an accidental Client Component import into a build error. `generateMetadata()` never receives or runs host loaders—even with `customMetadata`—so a normal request does not repeat host queries for metadata and rendering.
 
@@ -3205,263 +3228,12 @@ export default defineConfig({
 
 ## CLI
 
-The SDK includes a CLI for syncing configuration and content between your local environment and the CMS.
-
-### setup plan
-
-Show the read-only lifecycle for site creation, management-key setup, dashboard user access, and SDK env variables:
-
-```bash
-npx riverbankcms setup plan --env=remote
-```
-
-The SDK CLI cannot create remote sites, issue keys, or grant user access from a site-scoped management key. Do those privileged operations through the dashboard/admin surface or approved CMS repo tooling, then use the setup planner and `env status` to verify the SDK repo has the right `RIVERBANK_*` variables.
-
-### push-config
-
-Push schema/config surfaces to your CMS dashboard, including custom blocks, block field options/extensions, content type definitions/templates, SDK-managed site settings, and footer blocks:
-
-```bash
-npx riverbankcms push-config --dashboard <url>
-```
-
-Pages, content entries, navigation menus, and canonical events are content documents. Sync them with `riverbankcms push pages`, `riverbankcms push entries`, `riverbankcms push navigation`, or `riverbankcms push events`.
-
-Canonical event files in `content/events/*.json` include `preset`, `bookingScope`, and an explicit `occurrences` list. Each occurrence carries UTC `startsAt`/`endsAt` instants and its IANA `timeZone`; this supports one-off events and whole-series schedules without reconstructing dates from a recurrence summary. Files may also include `path` and `blocks`. `path` updates the linked event content entry route. `blocks` writes per-event entry-slot content, such as `blocks.main` for the built-in event template. Use stable block identifiers so repeat pushes update existing slot blocks; `push events` rejects duplicate event identifiers before writing. Default entry slots accept enabled SDK `custom.*` blocks, while explicit template `allowedBlocks` lists remain authoritative.
-
-The retired `schedule` object is not accepted. When upgrading a site with local event edits: preserve those edits, deploy the matching CMS API first, upgrade the SDK, run `riverbankcms pull events`, then reapply the edits to the canonical files. Existing occurrence schedules may be replayed exactly; changing an already-created schedule remains an explicit CMS capability gap.
-
-**Options:**
-
-| Option | Description |
-|--------|-------------|
-| `--api-key <key>` | Management API key (or set `RIVERBANK_*_MGMT_API_KEY`) |
-| `--dashboard <url>` | Dashboard URL (or set `RIVERBANK_*_DASHBOARD_URL`) |
-| `--config <path>` | Path to config file (default: `./riverbank.config.ts`) |
-| `--dry-run` | Validate config and preview schema/config surfaces without mutating the dashboard |
-
-**Example:**
-
-```bash
-# Using environment variables (local)
-export RIVERBANK_LOCAL_DASHBOARD_URL=https://www.riverbankcms.com
-export RIVERBANK_LOCAL_MGMT_API_KEY=bld_mgmt_sk_...
-npx riverbankcms push-config
-
-# Preview without applying
-npx riverbankcms push-config --dry-run
-
-# Or inline (remote)
-npx riverbankcms push-config \
-  --api-key bld_mgmt_sk_... \
-  --dashboard https://www.riverbankcms.com
-```
-
-### pull
-
-Download content from the CMS to local JSON files:
-
-```bash
-npx riverbankcms pull [scope] [type] [identifier]
-```
-
-**Scopes:**
-
-| Scope | Description |
-|-------|-------------|
-| (none) / `all` | Pull all content types |
-| `entries` | Pull all entries, a content type, or a single entry |
-| `pages` | Pull all pages or a single page |
-| `navigation` | Pull navigation menus |
-| `settings` | Pull site settings |
-| `forms` | Pull form definitions |
-| `venues` | Pull all event venues or one venue by slug |
-| `event-categories` | Pull all event categories or one category by identifier |
-| `events` | Pull all event series or one event by identifier |
-
-**Examples:**
-
-```bash
-# Pull all content
-npx riverbankcms pull
+The standalone `riverbankcms` package provides the CLI for syncing configuration
+and content between your SDK site and the CMS. Install it alongside
+`@riverbankcms/sdk`, then use the standalone package's
+[CLI reference](../cli/README.md) for setup, commands, environment behavior,
+and operational guidance.
 
-# Pull only forms
-npx riverbankcms pull forms
-
-# Pull entries for a specific content type
-npx riverbankcms pull entries blog-post
-
-# Pull one entry
-npx riverbankcms pull entries blog-post welcome
-
-# Pull one page
-npx riverbankcms pull pages home
-
-# Pull one canonical event
-npx riverbankcms pull events the-whole-in-your-heart
-
-# Pull from remote environment
-npx riverbankcms pull --env=remote
-
-# Sync media files between environments
-npx riverbankcms pull --env=remote --sync-media --yes
-
-# Overwrite target media on checksum mismatch (explicit / unsafe)
-npx riverbankcms pull --env=remote --sync-media --overwrite-media --yes
-
-# Download media referenced by identifiers
-npx riverbankcms pull --local-media
-```
-
-**Output Structure:**
-
-```
-content/
-├── entries/
-│   └── {content-type}/
-│       └── {identifier}.json
-├── pages/
-│   └── {identifier}.json
-├── forms/
-│   └── {slug}.json
-├── navigation.json
-├── settings.json
-├── media/
-│   ├── <identifier>.<ext>
-│   └── .manifest.json
-└── .meta/
-    ├── local/
-    │   └── {entity}.json  # Local CMS sync timestamps
-    └── remote/
-        └── {entity}.json  # Remote CMS sync timestamps
-```
-
-Older projects with flat `content/.meta/{entity}.json` files are read as a compatibility fallback. The CLI writes new metadata into the target-specific `local/` or `remote/` directory the next time you pull or update metadata.
-
-Note: `content/media/` is local cache and migration working data by default. Generated SDK sites gitignore `content/media/*` so large downloaded files are not staged accidentally, while allowing intentional small fixtures under `content/media/fixtures/`. `content/media/.manifest.json` is also cache data (identifier -> checksum/filename) and intentionally does not store env-specific `assetId`s.
-
-### push
-
-Push local content to the CMS with diff-based sync:
-
-```bash
-npx riverbankcms push [scope] [type] [identifier]
-```
-
-**Scopes:**
-
-| Scope | Description |
-|-------|-------------|
-| (none) / `all` | Push all content types |
-| `entries` | Push all entries, a content type, or a single entry |
-| `pages` | Push all pages or a single page with blocks |
-| `navigation` | Push navigation menus |
-| `settings` | Push `content/settings.json` only |
-| `forms` | Push form definitions |
-
-**Options:**
-
-| Option | Description |
-|--------|-------------|
-| `--dry-run` | Show what would be pushed without making changes |
-| `--yes` | Skip confirmation (required for `--env=remote`) |
-| `--force` | Push even if remote is newer |
-| `--force-update-asset` | Replace CMS media when identifiers conflict (local media sync only) |
-| `--sync-media` | Sync media files from local to remote environment |
-| `--overwrite-media` | When using `--sync-media`, overwrite target media on checksum mismatch |
-| `--json-diff` | Output JSON diff (`summary` or `full`) |
-| `--merge-remote` | Plan an entries/pages three-way merge for `--env=remote` that preserves remote edits |
-| `--verify-noop` | Re-fetch after an applied push and fail if changes remain |
-
-**Examples:**
-
-```bash
-# Preview changes (dry run)
-npx riverbankcms push --dry-run
-
-# Push all content
-npx riverbankcms push
-
-# Push only forms
-npx riverbankcms push forms
-
-# Push only site settings / branding
-npx riverbankcms push settings
-
-# Push to production with confirmation bypass
-npx riverbankcms push --env=remote --yes
-
-# Preview a production-safe merge for entries
-npx riverbankcms push entries blog-post --env=remote --merge-remote
-
-# Preview a production-safe merge for a page
-npx riverbankcms push pages home --env=remote --merge-remote
-
-# Apply that merge after reviewing the plan
-npx riverbankcms push entries blog-post --env=remote --merge-remote --yes
-
-# Get JSON diff for automation
-npx riverbankcms push --dry-run --json-diff=summary
-
-# Push to both environments and verify both are clean afterwards
-npx riverbankcms push --env=both --yes --verify-noop
-```
-
-**Remote-aware content merge:**
-
-`--merge-remote` is a safer production entries/pages workflow. It compares the last pulled base snapshot, your local files, and the current remote CMS, then reports a merge plan. Remote runs still default to dry-run; add `--yes` only after reviewing the plan. In v1 this supports entries and pages, is `--env=remote` only, and cannot be combined with `--force`, `--delete-orphaned`, or `--auto-pull-stale`. Page block changes are treated conservatively as conflicts unless remote blocks are unchanged.
-
-**Local content edit helpers:**
-
-`riverbankcms content edit ...` changes local `content/**` JSON files only. It previews by default and writes only with `--write`.
-
-```bash
-npx riverbankcms content edit remove-page-block home old-hero
-npx riverbankcms content edit move-page-block home intro --after hero --write
-npx riverbankcms content edit set-page-field home title --value "New title" --write
-npx riverbankcms content edit set-page-field home blocks[0].data.count --json-value 3
-```
-
-After editing, run `riverbankcms push --dry-run --diff`, then push with `--verify-noop` when ready.
-
-**Post-push verification:** `--verify-noop` re-reads local files after an applied push, fetches the target CMS, and fails if changes remain. It cannot be combined with `--dry-run`; remote targets need `--yes` so there is an applied push to verify. In JSON mode the CLI emits a `verification` object with `clean`, `dirty`, `fetch_failed`, or `unsupported_scope` status. A dirty result can also mean another actor changed remote content between push and verification.
-
-**Local Media (Identifiers):**
-
-- Add `identifier` to media fields (slug only, no extension)
-- Place files at `content/media/<identifier>.<ext>`
-- Use `npx riverbankcms push` to upload referenced files (default-on)
-- Use `--force-update-asset` to replace a CMS asset when checksums differ
-- Treat `content/media/*` as local cache/migration working data by default. For existing repos that already committed media, opt in with `git rm --cached -r content/media` after adding the generated ignore rule. Keep intentional small fixtures under `content/media/fixtures/`.
-
-**Site branding via `content/settings.json`:**
-
-```json
-{
-  "homepageId": null,
-  "seoDefaults": null,
-  "logoIdentifier": "positive-play-primary-logo",
-  "faviconIdentifier": "positive-play-primary-logo"
-}
-```
-
-- Keep branding files in `content/media/<identifier>.<ext>`
-- Run `npx riverbankcms push settings` to upload missing branding files and assign the site logo/favicon without pushing unrelated content
-- Run `npx riverbankcms pull settings` to round-trip the current identifier-based branding state
-- If the current CMS logo/favicon asset has no media identifier yet, pull warns and omits that field instead of writing a destructive clear
-- Dashboard branding edits and CLI pushes both write the same site settings columns, so pull before pushing if someone may have changed branding in the dashboard
-
-**Media portability (important):**
-
-- Content JSON is portable across environments; media references must be **identifier-only**.
-- Do not commit or hand-write `assetId`, `storagePath`, `storageBucket`, or `src` into content JSON.
-
-**Sync Behavior:**
-
-- **Creates** new content if identifier/slug doesn't exist
-- **Updates** existing content based on diff
-- **Never deletes** - removing from local doesn't delete from CMS
-- **Stale detection** - warns if remote changed since last pull (use `--force` to override)
 
 ## Next.js Catch-All Page Factory
 
@@ -3489,27 +3261,32 @@ export { generateMetadata };
 
 ### Production ISR Setup
 
-For production SDK sites, wire the catch-all route to Next ISR and let Riverbank discover published routes at build time. Preview deployments should set `RIVERBANK_PREVIEW_MODE=true`; `getISRConfig()` then returns `revalidate: 0` so draft previews stay dynamic.
+For production SDK sites, wire the catch-all route to Next ISR and let Riverbank discover published routes at build time. Next.js statically analyzes route configuration, so `revalidate` must be a literal rather than a function call or imported constant. Preview deployments should set `RIVERBANK_PREVIEW_MODE=true` and use the SDK preview integration, whose request-bound session handling keeps draft previews dynamic.
 
 ```tsx
 // src/app/[[...slug]]/page.tsx
 import {
   createCatchAllPage,
-  generateAllStaticParams,
-  getISRConfig,
+  createGenerateStaticParams,
 } from '@riverbankcms/sdk/next';
 
 import config from '@/riverbank.config';
 import { blockOverrides } from '@/lib/block-overrides';
 import { getRiverbankClient } from '@/lib/riverbank-client';
 
-export const revalidate = getISRConfig().revalidate;
+// Next.js route config values must remain statically analyzable literals.
+export const revalidate = 300;
 export const dynamicParams = true;
-export { generateAllStaticParams as generateStaticParams };
+export const generateStaticParams = createGenerateStaticParams({
+  getClient: getRiverbankClient,
+  siteId: config.siteId,
+  failureMode: 'throw',
+});
 
 const { Page, generateMetadata } = createCatchAllPage({
   getClient: getRiverbankClient,
   config,
+  searchParamsMode: 'ignore',
   blockOverrides,
 });
 
@@ -3517,7 +3294,12 @@ export default Page;
 export { generateMetadata };
 ```
 
-`generateAllStaticParams()` reads `RIVERBANK_API_KEY`, `RIVERBANK_SITE_ID`, and `NEXT_PUBLIC_DASHBOARD_URL`. By default it falls back to the homepage when route discovery fails, which keeps deploys from publishing an empty static route set silently. For strict production CI, fail the build instead:
+`searchParamsMode: 'ignore'` is required for this ISR shape because Next.js treats
+the page `searchParams` prop as a Dynamic API. Keep the default `dynamic` mode only
+when server-rendered themes, data loaders, redirects, or metadata genuinely depend
+on URL query parameters.
+
+If a site uses the SDK's generic environment variable names, `generateAllStaticParams()` is also available. It reads `RIVERBANK_API_KEY`, `RIVERBANK_SITE_ID`, and `NEXT_PUBLIC_DASHBOARD_URL`. By default it falls back to the homepage when route discovery fails. For strict production CI, fail the build instead:
 
 ```tsx
 import { generateAllStaticParams } from '@riverbankcms/sdk/next';
@@ -3864,7 +3646,7 @@ type CatchAllContext = {
 For maximum customization, skip `createCatchAllPage` and use the underlying helpers:
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk/rendering';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 import { generatePageMetadata } from '@riverbankcms/sdk/metadata';
 
 export default async function CustomPage({ params }) {
@@ -3879,6 +3661,9 @@ export default async function CustomPage({ params }) {
   });
 
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }