@riverbankcms/sdk 0.108.0 → 0.111.0

package/dist/cli/init-docs/content/cli-reference.md

@@ -8,11 +8,21 @@ All commands support these options:
 
 | Option           | Description                                                |
 | ---------------- | ---------------------------------------------------------- |
-| `--json`         | Output in JSON format for machine parsing                  |
+| `--json`         | Output a single JSON envelope for machine parsing          |
 | `--quiet`        | Minimal output (suppress non-essential messages)           |
 | `--env <target>` | Target environment: `local` (default), `remote`, or `both` |
 | `--remote`       | **[Deprecated]** Use `--env=remote` instead                |
 
+**The `--json` envelope (single-document contract):** under `--json`, *every* invocation emits **exactly one** JSON document on stdout:
+
+```json
+{ "ok": true, "command": "entry get", "result": { }, "warnings": [], "errors": [] }
+```
+
+- `ok: false` always carries a non-empty `errors` array, and the process exits non-zero — failures never print a stack trace on stdout. `ok: true` always has empty `errors`.
+- Commander's own paths ride the same envelope: `--help`, `--version`, and even an unknown command emit one document (an unknown command is `ok: false` with a non-zero exit).
+- Prompts are written to stderr, so JSON mode requires `--yes` for anything that would otherwise ask for confirmation. Non-envelope diagnostics (deprecation notices, warnings) go to stderr and never pollute the stdout document.
+
 **Environment targeting:**
 
 - `--env=local` (default): Target local Supabase/development environment
@@ -171,9 +181,9 @@ riverbankcms push event-categories     # Event categories
 riverbankcms push events               # Event series, routes, and entry slot blocks
 riverbankcms push --with-theme         # Also push theme when pushing all content
 
-# JSON diff output for agents
-riverbankcms push --dry-run --json-diff=summary
-riverbankcms push --dry-run --json-diff=full
+# JSON diff verbosity for agents (folded into the --json envelope)
+riverbankcms push --dry-run --json --diff-detail=summary
+riverbankcms push --dry-run --json --diff-detail=full
 ```
 
 **Agent-safe scoped push example:**
@@ -195,7 +205,8 @@ If unrelated local files would be included by a broad scope, stage a temporary c
 | `--force`              | Push even if remote is newer (skip stale check)                                      |
 | `--force-update-asset` | Replace CMS media when identifiers conflict (local media sync only)                  |
 | `--allow-truncated`    | Push even if remote content was truncated (may cause incomplete sync)                |
-| `--json-diff [mode]`   | Output JSON diff: `summary` or `full`                                                |
+| `--diff-detail <mode>` | Diff verbosity carried in the `--json` envelope: `summary` (default) or `full`       |
+| `--json-diff [mode]`   | **[Deprecated]** Alias of `--diff-detail`; folded into the `--json` envelope (warns on stderr) |
 | `--with-config`        | Push SDK schema/config before dependent file content                                |
 | `--with-theme`         | Also push theme when pushing all content                                             |
 | `--sync-media`         | Sync media files from local to remote environment                                    |
@@ -473,7 +484,23 @@ riverbankcms entry list blog-post --columns id,identifier --status published
 | `--limit <n>`     | Number of entries per page                                                                                                                                                                                |
 | `--page <n>`      | Page number (1-indexed)                                                                                                                                                                                   |
 | `--columns <csv>` | Comma-separated columns (e.g. `id,identifier,slug,status`). Aliases: `unpublished`→`hasUnpublishedChanges`, `updated`→`updatedAt`, `created`→`createdAt`, `published`→`publishedAt`, `type`→`contentType` |
-| `--status <draft  | published>`                                                                                                                                                                                               | Filter by status (applies to the returned page only) |
+| `--status <draft  | published>`                                                                                                                                                                                               | Filter by status. **Applies only to the returned page (post-pagination)** — for a complete cross-type overview of unpublished content use `riverbankcms drafts`. Passing `--status draft` emits a warning pointing you there. |
+
+---
+
+### entry scaffold
+
+Emit a machine-readable placeholder template plus fill-in diagnostics for a content type, derived from its field schema (pulled from the discovery catalog).
+
+```bash
+riverbankcms entry scaffold blog-post           # Template + diagnostics
+riverbankcms entry scaffold blog-post --json     # Rides the single JSON envelope
+riverbankcms entry scaffold blog-post > new-post.json   # Pipe the template to a file
+```
+
+Required fields are stubbed with placeholder sentinels (`"<REQUIRED: text>"`, `"<REQUIRED: media-identifier>"`, …) and optional fields are omitted. The template is **not** upsert-valid unfilled: replace every placeholder with a valid value and `entry upsert` accepts the result without structural edits. `entry upsert` runs the same validator as a pre-flight, so any unfilled sentinel is rejected before any HTTP request. `diagnostics` lists what to fill and flags fields that reference existing site resources (media, files, entry references).
+
+In human mode the template prints to stdout (so it pipes cleanly) and diagnostics go to stderr. An unknown content type fails with the list of available types.
 
 ---
 
@@ -1050,6 +1077,22 @@ riverbankcms publish-all blog-post --json
 
 ---
 
+## Drafts
+
+### drafts
+
+Cross-type overview of every page and entry with pending (unpublished) changes.
+
+```bash
+riverbankcms drafts                 # Table of everything with pending changes
+riverbankcms drafts --json          # One JSON envelope for agents
+riverbankcms drafts --env=remote    # Drafts on the remote site
+```
+
+This is the correct, server-filtered replacement for `entry list --status draft` (which filters only the returned page after pagination). The overview is enumerated fully server-side — a page or entry appears here if and only if it is a draft or carries unpublished changes — and the JSON `result` includes a `summary` with `pageCount` and `entryCount`.
+
+---
+
 ## Content Type Commands
 
 Commands for inspecting content types.
@@ -1143,7 +1186,7 @@ riverbankcms pull --no-meta
 riverbankcms entry list blog-post --json
 
 # Preview push diff as JSON
-riverbankcms push --dry-run --json-diff=summary
+riverbankcms push --dry-run --json --diff-detail=summary
 
 # Get page with blocks as JSON
 riverbankcms page get home --json

package/dist/cli/init-docs/content/content-management.md

@@ -245,8 +245,11 @@ riverbankcms entry get blog-post my-post
 # Check page status
 riverbankcms page get about
 
-# List with JSON to see status field
-riverbankcms entry list blog-post --json | jq '.entries[] | {identifier, status}'
+# List with JSON to see status field (--json wraps output in an envelope: reach into .result)
+riverbankcms entry list blog-post --json | jq '.result.entries[] | {identifier, status}'
+
+# Everything with pending changes, across all content types (server-filtered, uncapped)
+riverbankcms drafts
 ```
 
 ### Publishing Content
@@ -274,8 +277,8 @@ riverbankcms page unpublish about
 When you modify published content, it stays published but gains unpublished changes. The live site shows the last published version until you publish again.
 
 ```bash
-# Check for unpublished changes
-riverbankcms entry get blog-post my-post --json | jq '.hasUnpublishedChanges'
+# Check for unpublished changes (--json wraps output: the entry is under .result)
+riverbankcms entry get blog-post my-post --json | jq '.result.hasUnpublishedChanges'
 
 # Publish to apply pending changes
 riverbankcms entry publish blog-post my-post

package/dist/cli/init-docs/content/workflow-isr-revalidation.md

@@ -136,7 +136,7 @@ The same destination URL can also be configured from the Riverbank dashboard:
 https://www.example.com/api/revalidate
 ```
 
-SDK-site revalidation events include page and entry publish, unpublish, delete, and public path changes, along with navigation, theme, and site settings updates. Events send top-level `paths` and `tags`; the SDK handler normalizes and dedupes them before calling `revalidatePath()` and `revalidateTag()`.
+SDK-site revalidation events include page and entry publish, unpublish, delete, and public path changes, along with navigation, theme, site settings, and public event updates. Event updates are tag-authoritative: they always invalidate the site-wide public event and event-filter tags, and include the linked event path when one is known. Events send top-level `paths` and `tags`; the SDK handler normalizes and dedupes them before calling `revalidatePath()` and `revalidateTag()`.
 
 Some valid events are tags-only. Global render changes do not include explicit paths, and very large path sets degrade to tags-only delivery so webhook payloads stay bounded. Existing webhook endpoints may need their subscribed event list updated to receive the newer unpublish, delete, and path-change events.
 

package/dist/cli/init-docs/content/workflow-publish.md

@@ -57,17 +57,21 @@ riverbankcms page get <identifier>
 
 ### List All with Status (JSON)
 
+Under `--json` every command emits one envelope `{ ok, command, result, warnings, errors }`, so reach into `.result` when parsing with jq.
+
 ```bash
 # List entries with status
 riverbankcms entry list blog-post --json
 
 # Filter to see status fields (requires jq)
-riverbankcms entry list blog-post --json | jq '.entries[] | {identifier, status, hasUnpublishedChanges}'
+riverbankcms entry list blog-post --json | jq '.result.entries[] | {identifier, status, hasUnpublishedChanges}'
 
 # List pages with status
 riverbankcms page list --json
 ```
 
+To see everything with pending changes across all content types in one shot — correctly server-filtered, not capped by pagination — use `riverbankcms drafts` instead of scanning `entry list` page by page.
+
 ## Bulk Publishing via Push
 
 When using `riverbankcms push`, the status is synced based on your local content files.

package/dist/client/{DiscountCodeDisclosure-D6TOf6Hi.mjs → DiscountCodeDisclosure-C4xvTBux.mjs}

@@ -1,5 +1,5 @@
 "use client";
-import { t as themeButtonClassName } from "./buttons-EBjyslaX.mjs";
+import { tt as themeButtonClassName } from "./propsDecoder-wWN0tBDF.mjs";
 import { useId } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/api/types.ts

package/dist/client/{EventCombined.client-Dao3zxRk.mjs → EventCombined.client-Cr7G131j.mjs}

@@ -1,9 +1,8 @@
 "use client";
 import { t as clsx } from "./clsx-DgIEfj3H.mjs";
-import { A as formatDate, E as getEventRuntimeFiltersKey, F as formatEventTeacherLine, I as formatTime, L as getCardOrientation, N as formatEventPrice, R as getContainerClass, T as buildEventRuntimeFilters, U as getEventAvailability, V as resolveEventLinkProps, _t as assertNever, z as groupEventsByDate } from "./propsDecoder-BRWBiH7i.mjs";
-import { a as EventCardClient, i as EventPaginatedListView, n as useEventPagination, o as EventFilters, r as toError, t as useEventFilters } from "./useEventFilters-igGiK1re.mjs";
+import { A as formatDate, E as getEventRuntimeFiltersKey, F as formatEventTeacherLine, I as formatTime, L as getCardOrientation, N as formatEventPrice, R as getContainerClass, T as buildEventRuntimeFilters, U as getEventAvailability, V as resolveEventLinkProps, tt as themeButtonClassName, yt as assertNever, z as groupEventsByDate } from "./propsDecoder-wWN0tBDF.mjs";
+import { a as EventCardClient, i as EventPaginatedListView, n as useEventPagination, o as EventFilters, r as toError, t as useEventFilters } from "./useEventFilters-DKPN7hSY.mjs";
 import { n as useBlockApi } from "./context-BGZNlGXB.mjs";
-import { t as themeButtonClassName } from "./buttons-EBjyslaX.mjs";
 import { t as createBodyThemePortalRoot } from "./themePortalRoot-AGs4cE7t.mjs";
 import { t as ModalShell } from "./ModalShell-CqkBvBIC.mjs";
 import React, { createContext, useCallback, useContext, useEffect, useId, useMemo, useReducer, useRef, useState } from "react";

package/dist/client/{EventListing.client-B2NNt4y1.mjs → EventListing.client-CAjbseNy.mjs}

@@ -1,6 +1,6 @@
 "use client";
-import { T as buildEventRuntimeFilters } from "./propsDecoder-BRWBiH7i.mjs";
-import { i as EventPaginatedListView, n as useEventPagination, o as EventFilters, t as useEventFilters } from "./useEventFilters-igGiK1re.mjs";
+import { T as buildEventRuntimeFilters } from "./propsDecoder-wWN0tBDF.mjs";
+import { i as EventPaginatedListView, n as useEventPagination, o as EventFilters, t as useEventFilters } from "./useEventFilters-DKPN7hSY.mjs";
 import { useId, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/nodes/events/EventListing.client.tsx

package/dist/client/{LeafletStaticMap-BhwFo16w.mjs → LeafletStaticMap-BMlWfwz3.mjs}

@@ -1,5 +1,5 @@
 "use client";
-import { X as isRecord } from "./propsDecoder-BRWBiH7i.mjs";
+import { X as isRecord } from "./propsDecoder-wWN0tBDF.mjs";
 import { useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/nodes/shared/LeafletStaticMap.tsx

package/dist/client/{MagicLinkForm-BWnB7cMR.mjs → MagicLinkForm-ChdFz96y.mjs}

@@ -1,7 +1,6 @@
 "use client";
-import { _t as assertNever } from "./propsDecoder-BRWBiH7i.mjs";
+import { tt as themeButtonClassName, yt as assertNever } from "./propsDecoder-wWN0tBDF.mjs";
 import { n as useBlockApi } from "./context-BGZNlGXB.mjs";
-import { t as themeButtonClassName } from "./buttons-EBjyslaX.mjs";
 import { useEffect, useReducer, useState, useSyncExternalStore } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/shared/components/ClockIcon.tsx

package/dist/client/{StepIndicator-TzRiQ0BY.mjs → StepIndicator-7D3GaBeM.mjs}

@@ -1,6 +1,6 @@
 import { t as clsx } from "./clsx-DgIEfj3H.mjs";
-import { Ht as formatCurrencyAmount } from "./propsDecoder-BRWBiH7i.mjs";
-import { i as CheckIcon } from "./useDiscountCodeUi-D9RHpVoj.mjs";
+import { Wt as formatCurrencyAmount } from "./propsDecoder-wWN0tBDF.mjs";
+import { i as CheckIcon } from "./useDiscountCodeUi-cStSQI6C.mjs";
 import "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/shared/utils/formatting.ts

package/dist/client/{accordion-BPy-AJ4_.mjs → accordion-D8JTs2Si.mjs}

@@ -1,4 +1,4 @@
-import { t as defineIslandPropsDecoder } from "./propsDecoder-BRWBiH7i.mjs";
+import { t as defineIslandPropsDecoder } from "./propsDecoder-wWN0tBDF.mjs";
 //#region src/rendering/islands/enhancers/accordion.ts
 const decode = defineIslandPropsDecoder("accordion");
 function parseDefaultValues(value) {

package/dist/client/{bookingForm-BL4PGZds.mjs → bookingForm-H3DCRBHs.mjs}

@@ -1,13 +1,12 @@
 "use client";
-import { c as unsafeAsAppointmentServiceId, f as unsafeAsPassId, l as unsafeAsCustomerPassId, s as unsafeAsAppointmentResourceId, u as unsafeAsFormId } from "./colorTokenParts-CMugwvX_.mjs";
-import { n as buildBookingPaymentSelectionViewModel, t as usePolling } from "./usePolling-CI7MbsFB.mjs";
-import { Ct as reportWorkflowSuccess, Dt as formatBookingInstant, Ht as formatCurrencyAmount, Mt as resolveBookingTimeZoneId, St as reportWorkflowError, _t as assertNever, at as getBookingRedirectStateFromLocation, ct as isBookingServiceSlidingAmountInRange, dt as resolveAppointmentCheckoutVerificationState, ft as resolveBookingPaymentStep, gt as BOOKING_FORM_DATA_RESERVED_KEYS, ht as toSelectedCollectionOptionKind, it as formatBookingSubmissionPreparationError, jt as parseBookingLocalDate, kt as formatLocalScheduleDate, lt as parseBookingCurrencyInputToCents, mt as resolveDefaultBookingServiceId, nt as deriveBookingFormViewState, ot as getBookingServiceSlidingScale, pt as resolveBookingSiteId, rt as formatBookingCentsAsCurrencyInput, st as getBookingSuccessMessage, t as defineIslandPropsDecoder, tt as logger, ut as prepareBookingSubmission, vt as clearWorkflowFeedback, wt as addLocalScheduleDays, xt as okWith, yt as err } from "./propsDecoder-BRWBiH7i.mjs";
+import { d as unsafeAsCustomerPassId, f as unsafeAsFormId, l as unsafeAsAppointmentResourceId, m as unsafeAsPassId, u as unsafeAsAppointmentServiceId } from "./colorTokenParts-FSS3al6l.mjs";
+import { n as buildBookingPaymentSelectionViewModel, t as usePolling } from "./usePolling-BKAd6pkZ.mjs";
+import { Ct as okWith, Et as addLocalScheduleDays, Nt as parseBookingLocalDate, Pt as resolveBookingTimeZoneId, Tt as reportWorkflowSuccess, Wt as formatCurrencyAmount, _t as toSelectedCollectionOptionKind, at as formatBookingCentsAsCurrencyInput, bt as clearWorkflowFeedback, ct as getBookingServiceSlidingScale, dt as parseBookingCurrencyInputToCents, ft as prepareBookingSubmission, gt as resolveDefaultBookingServiceId, ht as resolveBookingSiteId, it as deriveBookingFormViewState, jt as formatLocalScheduleDate, kt as formatBookingInstant, lt as getBookingSuccessMessage, mt as resolveBookingPaymentStep, ot as formatBookingSubmissionPreparationError, pt as resolveAppointmentCheckoutVerificationState, rt as logger, st as getBookingRedirectStateFromLocation, t as defineIslandPropsDecoder, tt as themeButtonClassName, ut as isBookingServiceSlidingAmountInRange, vt as BOOKING_FORM_DATA_RESERVED_KEYS, wt as reportWorkflowError, xt as err, yt as assertNever } from "./propsDecoder-wWN0tBDF.mjs";
 import { n as useBlockApi, t as BlockApiProvider } from "./context-BGZNlGXB.mjs";
 import { n as isSpamProtectionEnabled, r as AltchaWidget, t as getChallengeUrl } from "./src-B833rYRr.mjs";
-import { i as CheckIcon, n as TerminalPanel, r as StateIcon, t as useDiscountCodeUi } from "./useDiscountCodeUi-D9RHpVoj.mjs";
-import { t as DiscountCodeDisclosure } from "./DiscountCodeDisclosure-D6TOf6Hi.mjs";
-import { n as SpinnerNode, t as StepIndicator } from "./StepIndicator-TzRiQ0BY.mjs";
-import { t as themeButtonClassName } from "./buttons-EBjyslaX.mjs";
+import { i as CheckIcon, n as TerminalPanel, r as StateIcon, t as useDiscountCodeUi } from "./useDiscountCodeUi-cStSQI6C.mjs";
+import { t as DiscountCodeDisclosure } from "./DiscountCodeDisclosure-C4xvTBux.mjs";
+import { n as SpinnerNode, t as StepIndicator } from "./StepIndicator-7D3GaBeM.mjs";
 import { t as FeedbackMessage } from "./FeedbackMessage-ByMrs3cr.mjs";
 import { n as getFieldValidationControlProps, t as FieldValidationMessage } from "./FieldValidationMessage-AYanWFb-.mjs";
 import { t as buildCheckoutReturnUrls } from "./checkoutUrls-Ct8Mxna3.mjs";