riverbankcms 0.9.0 → 0.11.0

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

@@ -11,6 +11,7 @@ All commands support these options:
 | `--json`         | Output a single JSON envelope for machine parsing          |
 | `--quiet`        | Minimal output (suppress non-essential messages)           |
 | `--env <target>` | Target project environment: `local` (default), `remote`, or `both` |
+| `--timeout <seconds>` | How long to wait for each dashboard request: a whole number from 1 to 600 (default 30, or ten minutes for media transfers). Overrides `RIVERBANK_REQUEST_TIMEOUT` |
 | `--remote`       | **[Deprecated]** Use `--env=remote` instead                |
 
 **The `--json` envelope (single-document contract):** under `--json`, *every* invocation emits **exactly one** JSON document on stdout:
@@ -63,11 +64,60 @@ RIVERBANK_REMOTE_MGMT_API_KEY=bld_mgmt_sk_...
 RIVERBANK_REMOTE_API_KEY=bld_live_sk_...  # Required for deploy command
 ```
 
+### Any environment
+
+```bash
+# Optional: how long to wait for each dashboard request, in seconds (1-600).
+# Unset: 30 for dashboard requests, ten minutes for media transfers.
+RIVERBANK_REQUEST_TIMEOUT=60
+```
+
+`--timeout` wins over `RIVERBANK_REQUEST_TIMEOUT`. When you set either one, it
+applies to every request, media uploads and downloads included. When neither
+is set, dashboard requests wait 30 seconds and media transfers get ten minutes.
+A value that isn't a whole number in range stops the command before it sends
+anything, so a typo never quietly falls back to the default.
+
 **Notes:**
 
 - Management API keys start with `bld_mgmt_sk_` (for write operations)
 - Content API keys start with `bld_live_sk_` (for read-only operations)
 
+## Network failures and recovery
+
+When a request never gets an answer from the dashboard, the error code is
+`sdk:network-error`, or `sdk:timeout` if the CLI's own time limit ran out. Both
+are kept separate from errors the dashboard sent back, such as a 409 conflict.
+The error's details carry a `transport` object saying what kind of failure it
+was, in the `--json` envelope and in the human output alike:
+
+| `transport.kind` | What it means | What to check |
+| ---------------- | ------------- | ------------- |
+| `dns` | The dashboard hostname couldn't be resolved | The dashboard URL in your environment |
+| `connect` | A connection to the dashboard couldn't be opened | That the dashboard is running and reachable |
+| `tls` | The TLS handshake failed | The certificate, or any proxy in between |
+| `reset` | The connection closed before a response arrived | See below: a write may have landed |
+| `timeout` | No response arrived in time | See below; `--timeout` allows longer |
+| `unknown` | Something else went wrong in transport | See below |
+
+`transport.code` is included when the platform reported a recognised code (for
+example `ENOTFOUND` or `ECONNRESET`). Nothing else from the underlying error is
+passed on: the message is fixed for each kind, so it can't echo hostnames,
+headers or keys.
+
+**A failed write may still have been saved.** With `dns`, `connect` and `tls`
+failures the request usually never left your machine. With `reset`, `timeout`
+and `unknown` it may well have reached the dashboard and been applied before the
+connection dropped. So after one of those on a request that can change
+something, the CLI tells you to read the record back before running the command
+again, rather than to retry. Whether a request can change something is set by
+the client for each operation, not guessed from the HTTP method, so read-only
+lookups such as a media delete preview get the plainer hint. The `--json`
+envelope shows it as `request.intent` (`read` or `write`). Some commands, such
+as `event offline`, `event delete` and `page design push`, do that readback for
+you (see [Event Commands](#event-commands) and
+[page design pull / page design push](#page-design-pull--page-design-push)).
+
 ---
 
 ## Setup Commands
@@ -622,6 +672,19 @@ riverbankcms page upsert about \
 | `--seo-title <title>`      | SEO title tag             |
 | `--seo-description <desc>` | SEO meta description      |
 
+A new page is created together with its route in one step, so a failed create
+doesn't leave a half-made page behind. If a new page's path is already taken,
+upsert is refused with a `409` that says why, and nothing is written:
+
+- `Path "<path>" is already used by page "<identifier>"` when another page
+  sits there. Use that page's identifier, or pick another path.
+- `Another route on this site already uses this path` when the path belongs to
+  something else, such as an entry or an event page.
+
+On a managed site, a new page has no stored design of its own and follows its
+site style's defaults until a design is saved for it, for example with
+`page design push`.
+
 ### page publish
 
 Publish a page.
@@ -660,6 +723,74 @@ riverbankcms page list --limit 10 --page 1
 riverbankcms page list --json
 ```
 
+### page design pull / page design push
+
+Move a page's draft design (its pinned block Looks and section breaks) onto
+another page built from the same blocks.
+
+```bash
+# Write the stored design to a file (stdout when --out is left off)
+riverbankcms page design pull <identifier> [--out <file>]
+riverbankcms page design pull radiant-women --out radiant-design.json
+
+# Write that design onto another page's draft
+riverbankcms page design push <identifier> <file>
+riverbankcms page design push radiant-women-celebration radiant-design.json
+```
+
+The file is JSON keyed by **block identifiers** (`hero-0`, `body-text-1`), not
+by block ids, so it can land on a page whose blocks were created separately.
+Every block the design mentions has to exist on the destination under the same
+identifier and kind, and every section break it sets has to sit between two
+blocks that are next to each other there.
+
+A few rules worth knowing before you rely on it:
+
+- **Same site style only.** A design only transfers between pages on the same
+  site style, and push refuses anything else before it looks at the blocks:
+  `This design comes from site style "<id>" and page <id> uses "<id>". Designs only transfer between pages on the same site style.`
+- **Managed sites only.** SDK sites style their pages in code and don't use
+  stored page designs, so push refuses them:
+  `Page <id> is on an SDK site, which does not use stored page designs.`
+- **Stored design only.** Pull exports what was saved for the page: its draft
+  design, or its published design when there's no draft (`--json` says which
+  as `source`). A page that has never had a design saved uses its site style's
+  defaults, and pull says so and writes nothing rather than turning those
+  defaults into pinned choices.
+- **Pins on deleted blocks are left out, and named.** A stored Look or break
+  that points at a block no longer on the page has no effect, so pull leaves it
+  out of the file and prints one line per pin it left out (for example
+  `Left out: a Look pinned on block <block-id>, which is no longer on page <id>.`).
+  They're listed under `omitted` in `--json`, and the pull still succeeds. A
+  break between two blocks that are both still on the page is kept even if
+  they're no longer next to each other; push then decides whether it fits the
+  destination.
+- **Draft only.** Push writes the page's draft design. It never publishes, and
+  it works on a page that's already published without changing that; publish
+  the page when you want the design live.
+- **Nothing is written on a refusal.** If the page flow, or any block, Look or
+  break, doesn't fit the destination, push lists each problem (for example
+  `The design refers to block "hero-0", which page <id> does not have.`) and
+  saves nothing.
+
+**What the revision check protects.** The design file carries no revision.
+Push reads the destination's current design revision immediately before it
+writes, so you never handle revision tokens. That only protects the short
+interval between that read and the write: if someone changes the destination's
+design in between, push fails with a conflict and writes nothing. It does
+**not** notice that the destination changed between an earlier `pull` and this
+`push`, so push overwrites whatever draft design the destination has at the
+time.
+
+**If the connection drops** during push, the CLI reads the destination's design
+back. It reports `Page <id>: draft design saved, confirmed by readback.` only
+when the page's *draft* design is exactly the design you sent. A matching
+published design doesn't count, because push only ever writes the draft. The
+dashboard may also adjust a design as it saves it (a site style that locks a
+block's Look adds that pin), and an adjusted draft no longer matches, so that
+case is reported as unknown too. Anything unconfirmed exits non-zero (see
+[Network failures and recovery](#network-failures-and-recovery)).
+
 ---
 
 ## Block Commands
@@ -787,6 +918,115 @@ riverbankcms navigation list --json
 
 ---
 
+## Event Commands
+
+Manage events and their dates.
+
+### event
+
+Manage event series directly through the CLI.
+
+```bash
+riverbankcms event list
+riverbankcms event get summer-fest
+riverbankcms event upsert summer-fest --file ./content/events/summer-fest.json
+riverbankcms event cancel summer-fest
+riverbankcms event offline summer-fest
+riverbankcms event delete summer-fest --yes
+riverbankcms event occurrence list summer-fest summer-run
+riverbankcms event occurrence add summer-fest summer-run \
+  --starts-at 2026-08-01T10:00 \
+  --duration-minutes 60
+riverbankcms event occurrence update summer-fest summer-run <occurrence-uuid> \
+  --capacity 20
+riverbankcms event occurrence cancel summer-fest summer-run <occurrence-uuid>
+riverbankcms event occurrence delete summer-fest summer-run <occurrence-uuid> --yes
+```
+
+`event upsert` and `push events` accept canonical event files with `path` and `blocks`. Events use native page authority: an `eventOffering` or `eventSeries` subject owns a page surface, and that surface owns its route, field content, publication state, and slots. `path` updates the page-surface route. `blocks` maps slot keys to surface-slot blocks, for example `blocks.main` for the built-in event template. Use stable block identifiers so repeat pushes update existing slot blocks safely. Unknown slot keys or block kinds fail validation; default slots accept enabled SDK `custom.*` blocks, while explicit template `allowedBlocks` lists remain authoritative. Ordinary editorial entries continue to use the separate `entry` commands and content-entry model described above.
+
+For an online Event page, updating `content` publishes its field content immediately, matching the dashboard Content tab. The same save updates the image shown in run listings. Route, block and layout changes retain their separate draft and publish flow.
+
+#### Taking an event offline and deleting it
+
+`event delete` is refused while the event's page is still published, and the
+page cannot go offline while any run is live. `event offline` handles both in
+one call: it takes every live run and the Event page offline together, in one
+transaction on the dashboard. That makes deleting a published event a sequence
+of two explicit commands:
+
+```bash
+riverbankcms event offline summer-fest
+riverbankcms event delete summer-fest --yes
+```
+
+Running `event offline` again is safe — it reports `Event summer-fest was
+already offline.` and writes nothing. There is no `--offline-first` flag on
+`event delete`; the two steps stay separate so the deletion guards for
+registrations and payments are never bundled into a lifecycle change. That also
+means registrations don't stop `event offline` (existing bookings are left
+alone), but they do stop `event delete`: an event with registrations or
+payments can go offline and still be refused deletion.
+
+Under `--json` the outcome travels as typed data: either
+`{ "kind": "applied", "changedRunIds": [...], "pageTakenOffline": true }` or
+`{ "kind": "already-offline" }`.
+
+**If the connection drops.** A network error or timeout on either command tells
+you nothing about whether the dashboard applied the change, so the CLI does not
+guess and never tells you to retry. Instead it reads the event back:
+
+- `event offline` reports success only when every run reads back non-live and
+  the event's `pageState` reads back `offline`. If the dashboard is old enough
+  not to report `pageState` at all, the page cannot be proven and the outcome
+  stays unknown.
+- `event delete` reads the event immediately before sending the delete. If that
+  read found the event and the readback afterwards finds nothing, the deletion
+  is reported as a success "confirmed by readback".
+- Anything else is reported as unknown, with a non-zero exit code:
+  `The dashboard did not confirm this change and it could not be read back.
+  Check the event in the dashboard before running this again.`
+  The error keeps the original `sdk:network-error` or `sdk:timeout` code and
+  its `transport` kind (see [Network failures and recovery](#network-failures-and-recovery)).
+
+#### Individual event dates
+
+`event occurrence` manages bookable dates without replacing the parent event
+series. Mutation commands always use the occurrence UUID shown by `list`; a
+calendar date is never accepted as an identity.
+
+- `list <event-identifier> <run-identifier>` shows all future dates, including
+  cancelled dates. The parent Event and run are both explicit, so multi-run
+  Events never rely on an ambiguous identifier.
+  Add `--all` to include history or `--status scheduled|cancelled|completed` to
+  filter. The CLI follows the API's bounded pages, while `--json` keeps the
+  canonical UTC instants in its single result envelope.
+- `add` requires `--starts-at` plus exactly one of `--ends-at` or
+  `--duration-minutes`. `update` accepts the same complete schedule replacement,
+  `--capacity <positive-integer>`, or `--inherit-capacity`.
+- Local timestamps such as `2026-08-01T10:00` use the event's effective
+  timezone: occurrence venue override, then series venue, then site default.
+  Offset timestamps such as `2026-08-01T10:00+01:00` are absolute instants.
+  Do not mix the two modes in one start/end pair.
+- Local times that do not exist during a spring clock change are rejected.
+  Repeated autumn times are also rejected unless both start and end include
+  explicit offsets. A duration is elapsed real time from the resolved start,
+  even when clocks change during the date.
+- A manual date or recurring exception can be rescheduled. A generated
+  recurring date cannot be moved or deleted because schedule reconciliation
+  owns it; cancel the generated date and add a replacement exception instead.
+  Cancellation preserves registrations and is idempotent. Deletion requires
+  zero registrations and confirmation (`--yes` for remote or JSON use).
+
+`pull events` writes the complete non-cancelled occurrence schedule into each
+portable event file. `push events` creates those rows for a new series and
+accepts an exact replay for an existing series. It deliberately rejects
+existing-series additions, removals, or retiming; use the imperative occurrence
+commands for those operational changes. Cancelled occurrence tombstones remain
+in the CMS and are omitted from portable authored content.
+
+---
+
 ## Delete Commands
 
 Delete content from the CMS.
@@ -987,64 +1227,6 @@ riverbankcms compare events
 - `0`: Content is in sync
 - `1`: Differences found
 
-### event
-
-Manage event series directly through the CLI.
-
-```bash
-riverbankcms event list
-riverbankcms event get summer-fest
-riverbankcms event upsert summer-fest --file ./content/events/summer-fest.json
-riverbankcms event cancel summer-fest
-riverbankcms event delete summer-fest --yes
-riverbankcms event occurrence list summer-fest summer-run
-riverbankcms event occurrence add summer-fest summer-run \
-  --starts-at 2026-08-01T10:00 \
-  --duration-minutes 60
-riverbankcms event occurrence update summer-fest summer-run <occurrence-uuid> \
-  --capacity 20
-riverbankcms event occurrence cancel summer-fest summer-run <occurrence-uuid>
-riverbankcms event occurrence delete summer-fest summer-run <occurrence-uuid> --yes
-```
-
-`event upsert` and `push events` accept canonical event files with `path` and `blocks`. Events use native page authority: an `eventOffering` or `eventSeries` subject owns a page surface, and that surface owns its route, field content, publication state, and slots. `path` updates the page-surface route. `blocks` maps slot keys to surface-slot blocks, for example `blocks.main` for the built-in event template. Use stable block identifiers so repeat pushes update existing slot blocks safely. Unknown slot keys or block kinds fail validation; default slots accept enabled SDK `custom.*` blocks, while explicit template `allowedBlocks` lists remain authoritative. Ordinary editorial entries continue to use the separate `entry` commands and content-entry model described above.
-
-#### Individual event dates
-
-`event occurrence` manages bookable dates without replacing the parent event
-series. Mutation commands always use the occurrence UUID shown by `list`; a
-calendar date is never accepted as an identity.
-
-- `list <event-identifier> <run-identifier>` shows all future dates, including
-  cancelled dates. The parent Event and run are both explicit, so multi-run
-  Events never rely on an ambiguous identifier.
-  Add `--all` to include history or `--status scheduled|cancelled|completed` to
-  filter. The CLI follows the API's bounded pages, while `--json` keeps the
-  canonical UTC instants in its single result envelope.
-- `add` requires `--starts-at` plus exactly one of `--ends-at` or
-  `--duration-minutes`. `update` accepts the same complete schedule replacement,
-  `--capacity <positive-integer>`, or `--inherit-capacity`.
-- Local timestamps such as `2026-08-01T10:00` use the event's effective
-  timezone: occurrence venue override, then series venue, then site default.
-  Offset timestamps such as `2026-08-01T10:00+01:00` are absolute instants.
-  Do not mix the two modes in one start/end pair.
-- Local times that do not exist during a spring clock change are rejected.
-  Repeated autumn times are also rejected unless both start and end include
-  explicit offsets. A duration is elapsed real time from the resolved start,
-  even when clocks change during the date.
-- A manual date or recurring exception can be rescheduled. A generated
-  recurring date cannot be moved or deleted because schedule reconciliation
-  owns it; cancel the generated date and add a replacement exception instead.
-  Cancellation preserves registrations and is idempotent. Deletion requires
-  zero registrations and confirmation (`--yes` for remote or JSON use).
-
-`pull events` writes the complete non-cancelled occurrence schedule into each
-portable event file. `push events` creates those rows for a new series and
-accepts an exact replay for an existing series. It deliberately rejects
-existing-series additions, removals, or retiming; use the imperative occurrence
-commands for those operational changes. Cancelled occurrence tombstones remain
-in the CMS and are omitted from portable authored content.
-
 ### verify
 
 Compare local SDK config content types against target site.

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

@@ -743,14 +743,18 @@ Footer links are managed via the site's footer navigation menu (see `content/nav
   ISO datetimes and every item carries the event's IANA timezone.
 - Run `venueRef` and `categoryRef` values reference identifiers from venues and event-categories.
 - `status`: "draft", "active", "completed", "cancelled", or "archived"
-- `visibility`: "private", "public", or "unlisted"
+- `visibility`: "public" (listed on the site and findable in search) or
+  "unlisted" (the link works and people can book, but it is left out of
+  listings and search). A run that has not gone live yet is a "draft"
+  `status`, not a listing choice.
 - Event page content is owned by the native `eventOffering` or `eventSeries` page-surface subject.
+- Updating an online Event's `content` through `event upsert` or `push events` publishes its field content immediately, as the dashboard Content tab does. Its route, blocks and layout keep their separate draft and publish flow.
 - `blocks` writes to the event page surface's template-defined surface slots. The default event template declares `blocks.main`.
 - Use stable block `identifier` values. Re-pushing the same event updates matching slot blocks instead of creating duplicates.
 - Default surface slots accept built-in content blocks plus enabled SDK custom blocks. If a template sets `allowedBlocks`, that explicit list is authoritative.
 - `riverbankcms push events` aborts when two `content/events/*.json` files use the same `identifier`; merge or delete stale duplicates before pushing.
 
-See `cli-reference.md` for event-related CLI commands: `riverbankcms push/pull venues|event-categories|events`.
+See `cli-reference.md` for event-related CLI commands: `riverbankcms push/pull venues|event-categories|events`, plus `riverbankcms event offline` and `riverbankcms event delete` for taking a published event offline and then removing it.
 
 `riverbankcms pull events` writes every non-cancelled occurrence to the event
 file. Pushing a new event creates that explicit schedule, and pushing an

package/dist/cli/init-docs/content/workflow-create-page.md

@@ -190,6 +190,10 @@ riverbankcms page publish about
 
 If the page identifier already exists, `upsert` will update it. This is intentional - use unique identifiers for new pages.
 
+### Path already in use
+
+Creating a page on a path that another page or route already uses fails with a `409` and writes nothing. The message names the page that holds the path when there is one (`Path "/contact" is already used by page "contact-us"`); otherwise it says another route on the site uses it, such as an entry or event page. Pick a different path, or upsert the existing page by its identifier instead.
+
 ### Block not appearing
 
 - Verify the block was created: `riverbankcms block get <page> <block-id>`

package/dist/{eventUpsertInputSchema-CqHIJp9H.mjs → eventUpsertInputSchema-DFPgv4ay.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { a as classifySdkEventBookingOffer, i as classifySdkEventSchedule, r as sdkEventUpsertOptionalFieldSchemas } from "./sdk-event-upsert-BNxbxaA0.mjs";
-import { l as EVENT_PRESET_VALUES } from "./src-DbmhanBI.mjs";
+import { a as classifySdkEventSchedule, i as sdkEventUpsertOptionalFieldSchemas, n as sdkCourseBookingSettingsSchema, o as classifySdkEventBookingOffer } from "./sdk-event-upsert-CRQseim3.mjs";
+import { l as EVENT_PRESET_VALUES } from "./src-CiZrHLCj.mjs";
 import { z } from "zod";
 
 //#region ../blocks/src/lib/typeGuards.ts
@@ -4804,6 +4804,7 @@ const eventRunInputSchema = z.object({
 }).strict();
 const eventUpsertInputSchema = z.object({
 	identifier: z.string().min(1).optional(),
+	courseBooking: sdkCourseBookingSettingsSchema.optional(),
 	title: z.string().min(1, "title is required"),
 	slug: z.string().min(1).optional(),
 	content: z.record(z.string(), z.unknown()).optional(),

package/dist/{load-config-Cf5uPEAn.mjs → load-config-B7AiZalH.mjs}

@@ -7,7 +7,7 @@ import { existsSync as existsSync$1 } from "fs";
 import { fileURLToPath } from "url";
 
 //#region package.json
-var version = "0.9.0";
+var version = "0.11.0";
 var peerDependencies = { "@riverbankcms/sdk": ">=0.139.0 <1.0.0" };
 var package_default = {
 	name: "riverbankcms",
@@ -83,7 +83,7 @@ var package_default = {
 //#endregion
 //#region src/version.ts
 /** The package manifest is the source-run fallback; builds inject this value. */
-const CLI_VERSION = typeof "0.9.0" === "string" ? "0.9.0" : version;
+const CLI_VERSION = typeof "0.11.0" === "string" ? "0.11.0" : version;
 /**
 * The CLI's SDK peer range is bundled from the CLI manifest alongside its
 * version. Runtime config loading uses this value as the single compatibility

package/dist/load-config-ELWKxyb5.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { t as loadConfigFile } from "./load-config-B7AiZalH.mjs";
+
+export { loadConfigFile };