@riverbankcms/sdk 0.96.0 → 0.99.0

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

@@ -61,6 +61,29 @@ RIVERBANK_REMOTE_API_KEY=bld_live_sk_...  # Required for deploy command
 
 ---
 
+## Setup Commands
+
+### setup plan
+
+Show the safe site, key, user access, and env setup lifecycle for the selected environment.
+
+```bash
+# Show local setup status and lifecycle
+riverbankcms setup plan
+
+# Show remote setup status and lifecycle
+riverbankcms setup plan --env=remote
+
+# Show both targets as JSON
+riverbankcms setup plan --env=both --json
+```
+
+The setup planner is read-only. It does not create sites, issue API keys, or grant dashboard access. Those operations require a dashboard/admin actor or an approved CMS repo script with service-role/admin credentials. SDK management keys are site-scoped and are only used for verifying access and syncing content/config for an existing site.
+
+Use this command when a project has missing `RIVERBANK_*_SITE_ID`, `RIVERBANK_*_DASHBOARD_URL`, or `RIVERBANK_*_MGMT_API_KEY` values, or when onboarding an existing remote site into an SDK repo.
+
+---
+
 ## Content Sync Commands
 
 ### pull
@@ -173,7 +196,7 @@ If unrelated local files would be included by a broad scope, stage a temporary c
 | `--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`                                                |
-| `--with-config`        | Also push SDK schema/config after file content                                       |
+| `--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                                    |
 | `--overwrite-media`    | When using `--sync-media`, overwrite target media on checksum mismatch               |
@@ -262,6 +285,8 @@ riverbankcms push --env=both --yes --verify-noop
 
 Push compares local metadata timestamps against the remote CMS. If the remote has newer changes than your last pull, push aborts by default to prevent overwriting someone else's edits.
 
+Metadata is stored separately per CLI target under `content/.meta/local/` and `content/.meta/remote/`, with a small target marker so local and remote pulls do not overwrite each other's stale-detection base. Older flat `content/.meta/*.json` files are still read as a fallback and are written forward to the scoped layout on the next pull or metadata update.
+
 Options for handling stale content:
 
 - **Interactive prompt** (default in TTY): Push asks whether to pull the stale items and retry.
@@ -328,12 +353,15 @@ Push SDK configuration to the CMS dashboard.
 
 ```bash
 riverbankcms push-config
+riverbankcms push-config --dry-run
 riverbankcms push-config --env=remote
 riverbankcms push-config --config ./src/riverbank.config.ts
 ```
 
 Syncs SDK schema/config surfaces such as custom blocks, block field options/extensions, content type definitions/templates, SDK-managed site settings, and footer blocks. Pages, entries, and navigation menus are synced with explicit `riverbankcms push` scopes.
 
+Use `--dry-run` to validate config and preview the schema/config surfaces that would be considered without mutating the dashboard.
+
 If `push-config` returns template binding validation errors, treat them as schema feedback. For example, a content type `reference` field should bind to a custom block `reference` field with the same `referenceKind`, not to a plain `text` field.
 
 This syncs:

package/dist/cli/init-docs/content/getting-started.md

@@ -127,6 +127,14 @@ Additional content configuration for scaffolding.
 
 ## Working with Remote/Production
 
+If the remote site, management key, or dashboard user access is not set up yet, start with the safe setup planner:
+
+```bash
+riverbankcms setup plan --env=remote
+```
+
+See `workflows/remote-setup.md` for the full site/key/user lifecycle. The SDK CLI uses site-scoped management keys for sync; remote site creation, key issuance, and user access changes stay in the dashboard/admin surface.
+
 Use `--env=remote` to target production instead of local:
 
 ```bash

package/dist/cli/init-docs/content/workflow-agent-safe-sync.md

@@ -17,7 +17,7 @@ Use the CLI environment flag:
 ```bash
 riverbankcms pull --env=remote
 riverbankcms push pages privacy-policy --env=remote --dry-run
-riverbankcms push-config --env=remote
+riverbankcms push-config --env=remote --dry-run
 ```
 
 Do not rely on `RIVERBANK_ENV=remote riverbankcms ...` for CLI sync commands. Site projects often load `.env.local`, and an existing `RIVERBANK_ENV=local` value can override the shell value in config-loading paths. The CLI `--env` flag is explicit and survives project env defaults.
@@ -70,6 +70,8 @@ riverbankcms push-config ...
 
 `push-config` does not replace `push pages` or `push entries`; it syncs schema/config surfaces. If config validation fails, read the field errors as schema feedback before working around them in the site.
 
+Run `riverbankcms push-config --dry-run` before applying schema/config changes to validate the config and preview the config surfaces without mutating the dashboard.
+
 ## Before Applying
 
 Checklist:

package/dist/cli/init-docs/content/workflow-preview-mode.md

@@ -69,6 +69,12 @@ The example logs preview exchange failures with `console.warn`; replace it with
 
 If you are upgrading an existing generated site, make sure your proxy imports `getCmsConfig`, is declared `async`, and passes `dashboardUrl` into `handlePreviewTokens`. Without the dashboard URL, visits with `preview_code` cannot exchange the short-lived code for preview cookies.
 
+## Public Runtime Adapter Contracts
+
+Use `resolveRouteDecision` for middleware or redirect-only checks. It returns only `contentExists`, `redirect`, `notFound`, or `loadFailed`; use `resolveRouteOutcome` only when the caller needs the full content payload for rendering.
+
+Event registration endpoints use the `public-event-ticket-selection.v2` transport shape: pass `ticketSelections: [{ ticketTypeId, quantity }]`. Legacy top-level `ticketsCount` or `ticketTypeId` fields are rejected so stale clients fail visibly instead of silently selecting the wrong tickets.
+
 ## Add Preview Keep-Alive Route
 
 Create `src/app/api/preview/keep-alive/route.ts`:

package/dist/cli/init-docs/content/workflow-remote-setup.md

@@ -0,0 +1,51 @@
+# Remote Site, Key, and User Access Setup
+
+This SDK project can sync content once it has a site ID, dashboard URL, and site-scoped management key. Creating the remote site, issuing keys, and granting dashboard user access are admin operations.
+
+## Check the Plan
+
+Run the setup planner before copying secrets or pushing to production:
+
+```bash
+riverbankcms setup plan --env=remote
+```
+
+For a machine-readable checklist:
+
+```bash
+riverbankcms setup plan --env=remote --json
+```
+
+## Authority Model
+
+- Dashboard/admin users can create sites, issue site-scoped management keys, and grant dashboard access.
+- Approved CMS repo scripts can do the same when run with service-role/admin credentials.
+- SDK management keys can verify access and sync content/config for one site. They cannot create sites, issue new keys, or grant user access.
+
+Do not put platform-admin, service-role, or user-session credentials in an SDK site repository.
+
+## Remote Setup Lifecycle
+
+1. Create or choose the remote site from the dashboard/admin surface.
+2. Generate a management key for that site.
+3. Grant the site owner or editor dashboard access from the dashboard/admin surface.
+4. Add the remote SDK variables to `.env.local`:
+
+```bash
+RIVERBANK_REMOTE_SITE_ID=your-site-id
+RIVERBANK_REMOTE_DASHBOARD_URL=https://your-dashboard.example.com
+RIVERBANK_REMOTE_MGMT_API_KEY=bld_mgmt_sk_...
+RIVERBANK_REMOTE_API_KEY=bld_live_sk_... # optional for public content fetching/deploy
+```
+
+5. Verify the SDK can reach the site:
+
+```bash
+riverbankcms env status --env=remote
+riverbankcms pull --env=remote --dry-run
+riverbankcms push --env=remote --dry-run
+```
+
+## Existing Sites and Users
+
+For an existing remote site, copy its site ID and create a fresh site-scoped management key if the old one is missing or should be rotated. Associate existing users with the site through the dashboard/admin surface. If the user does not exist yet, invite or create them through that approved flow rather than through the SDK CLI.

package/dist/client/{accordion-GUNXIIZR.mjs → accordion-QSUEYL4L.mjs}

@@ -1,5 +1,5 @@
-import { defineIslandPropsDecoder } from './chunk-GWCRCJLB.mjs';
-import './chunk-PCHACQEB.mjs';
+import { defineIslandPropsDecoder } from './chunk-CYJ3MUFP.mjs';
+import './chunk-IIUIKJ4K.mjs';
 
 // src/rendering/islands/enhancers/accordion.ts
 var decode = defineIslandPropsDecoder("accordion");