@riverbankcms/sdk 0.7.0 → 0.7.3

package/dist/cli/init-docs/content/agents-section.md

@@ -0,0 +1,50 @@
+## RiverbankCMS SDK Context
+
+This repository is a site using **RiverbankCMS** as a headless CMS via the `@riverbankcms/sdk` package.
+
+### What This Means
+
+- Content (pages, entries, blocks, navigation) is managed in RiverbankCMS
+- The SDK CLI syncs content between local files and the CMS
+- Configuration lives in `riverbank.config.ts`
+- You work with local content files, then push changes to the CMS
+
+### Key Configuration Files
+
+- `riverbank.config.ts` - Site schema, custom blocks, field extensions
+- `.env.local` - Local CMS credentials (never commit)
+
+### Agent Documentation
+
+Detailed documentation is available in `.riverbank/docs/`:
+
+- `getting-started.md` - Quick orientation for working with this site
+- `cli-reference.md` - Full SDK CLI command reference
+- `content-management.md` - Content model and sync workflows
+- `schema.md` - Site-specific schema (auto-generated from config)
+- `block-types.md` - Available block types (auto-generated)
+- `workflows/` - Step-by-step guides for common tasks
+- `site-workflows/` - Site-specific workflows and customizations
+
+### Quick Commands
+
+```bash
+riverbankcms pull              # Download all content from CMS
+riverbankcms push --dry-run    # Preview what would be pushed
+riverbankcms push              # Push local changes to CMS
+riverbankcms push-config       # Sync riverbank.config.ts to CMS
+```
+
+### Working with Content
+
+1. **Pull latest**: `riverbankcms pull` downloads content to `content/` directory
+2. **Make changes**: Edit JSON files or use CLI commands
+3. **Preview**: `riverbankcms push --dry-run` shows what would change
+4. **Push**: `riverbankcms push` applies changes to CMS
+
+### Code Quality Guidelines
+
+- Prefer functional, composable helpers over large classes
+- Keep changes small and focused
+- Use typed content from the SDK where available
+- Follow existing patterns in the codebase

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

@@ -0,0 +1,574 @@
+# SDK CLI Reference
+
+The RiverbankCMS SDK CLI (`riverbankcms`) manages content synchronization between local files and the CMS.
+
+## Global Options
+
+All commands support these options:
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output in JSON format for machine parsing |
+| `--quiet` | Minimal output (suppress non-essential messages) |
+| `--remote` | Use remote/production environment instead of local |
+
+## Environment Variables
+
+### Local Environment (default)
+
+```bash
+RIVERBANK_LOCAL_SITE_ID=your-site-id
+RIVERBANK_LOCAL_DASHBOARD_URL=http://localhost:4000
+RIVERBANK_LOCAL_MGMT_API_KEY=bld_mgmt_sk_...
+```
+
+### Remote Environment (--remote)
+
+```bash
+RIVERBANK_REMOTE_SITE_ID=your-site-id
+RIVERBANK_REMOTE_DASHBOARD_URL=https://your-dashboard.riverbankcms.com
+RIVERBANK_REMOTE_MGMT_API_KEY=bld_mgmt_sk_...
+```
+
+---
+
+## Content Sync Commands
+
+### pull
+
+Download content from the CMS to local files.
+
+```bash
+# Pull all content
+riverbankcms pull
+
+# Pull from production
+riverbankcms pull --remote
+
+# Pull specific content types
+riverbankcms pull entries              # All entries
+riverbankcms pull entries blog-post    # Specific content type
+riverbankcms pull pages                # All pages with blocks
+riverbankcms pull navigation           # Navigation menus
+riverbankcms pull settings             # Site settings
+
+# Custom output directory
+riverbankcms pull --output ./src/content
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--output <dir>` | Output directory (default: ./content) |
+| `--force` | Overwrite existing files without prompting |
+| `--yes` | Skip confirmation prompt |
+
+### push
+
+Push local content changes to the CMS.
+
+```bash
+# Push all content
+riverbankcms push
+
+# Preview changes without applying
+riverbankcms push --dry-run
+
+# Push to production (requires --yes)
+riverbankcms push --remote --yes
+
+# Push specific content types
+riverbankcms push entries              # All entries
+riverbankcms push entries blog-post    # Specific content type
+riverbankcms push pages                # All pages with blocks
+riverbankcms push navigation           # Navigation menus
+
+# JSON diff output for agents
+riverbankcms push --dry-run --json-diff=summary
+riverbankcms push --dry-run --json-diff=full
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--content-dir <dir>` | Content directory (overrides config) |
+| `--dry-run` | Show changes without applying |
+| `--yes` | Skip confirmation (required for --remote) |
+| `--force` | Push even if remote is newer (skip stale check) |
+| `--json-diff [mode]` | Output JSON diff: `summary` or `full` |
+
+**Sync Behavior** (configured in `riverbank.config.ts`):
+
+```typescript
+export default defineConfig({
+  siteId: '...',
+  sync: {
+    existingEntries: 'update',  // 'skip' (default) or 'update'
+    contentTarget: 'draft',     // 'draft' (default) or 'publish'
+  },
+});
+```
+
+### push-config
+
+Push SDK configuration to the CMS dashboard.
+
+```bash
+riverbankcms push-config
+riverbankcms push-config --remote
+riverbankcms push-config --config ./src/riverbank.config.ts
+```
+
+This syncs:
+- Custom blocks
+- Block field extensions
+- Block field options
+- Content type definitions
+- Content scaffolding (pages, entries, navigation)
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--api-key <key>` | Management API key |
+| `--dashboard <url>` | Dashboard URL |
+| `--config <path>` | Config file path |
+
+---
+
+## Entry Commands
+
+Manage content entries.
+
+### entry upsert
+
+Create or update an entry.
+
+```bash
+# With inline JSON data
+riverbankcms entry upsert <type> <identifier> --data '{"title": "Hello World"}'
+
+# With JSON file
+riverbankcms entry upsert <type> <identifier> --file ./data.json
+
+# With individual fields
+riverbankcms entry upsert blog-post my-post \
+  --slug my-post \
+  --title "My Blog Post"
+```
+
+**Arguments:**
+- `<type>` - Content type key (e.g., `blog-post`, `product`)
+- `<identifier>` - Unique identifier for the entry
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--data <json>` | Entry data as JSON string |
+| `--file <path>` | Path to JSON file with entry data |
+| `--slug <slug>` | Entry slug |
+| `--title <title>` | Entry title |
+
+### entry publish
+
+Publish an entry.
+
+```bash
+riverbankcms entry publish <type> <identifier>
+riverbankcms entry publish blog-post my-post
+```
+
+### entry unpublish
+
+Unpublish an entry (revert to draft).
+
+```bash
+riverbankcms entry unpublish <type> <identifier>
+riverbankcms entry unpublish blog-post my-post
+```
+
+### entry get
+
+Retrieve a single entry.
+
+```bash
+riverbankcms entry get <type> <identifier>
+riverbankcms entry get blog-post my-post
+riverbankcms entry get blog-post my-post --json
+```
+
+### entry list
+
+List entries for a content type.
+
+```bash
+riverbankcms entry list <type>
+riverbankcms entry list blog-post
+riverbankcms entry list blog-post --limit 10 --page 2
+riverbankcms entry list blog-post --json
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--limit <n>` | Number of entries per page |
+| `--page <n>` | Page number (1-indexed) |
+
+---
+
+## Page Commands
+
+Manage pages.
+
+### page upsert
+
+Create or update a page.
+
+```bash
+riverbankcms page upsert <identifier> --title "Page Title" --path /url-path
+
+# Full example
+riverbankcms page upsert about \
+  --title "About Us" \
+  --path /about \
+  --seo-title "About Us | Company Name" \
+  --seo-description "Learn more about our company"
+```
+
+**Arguments:**
+- `<identifier>` - Unique identifier for the page
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--title <title>` | Page title |
+| `--path <path>` | URL path (e.g., `/about`) |
+| `--seo-title <title>` | SEO title tag |
+| `--seo-description <desc>` | SEO meta description |
+
+### page publish
+
+Publish a page.
+
+```bash
+riverbankcms page publish <identifier>
+riverbankcms page publish about
+```
+
+### page unpublish
+
+Unpublish a page (revert to draft).
+
+```bash
+riverbankcms page unpublish <identifier>
+riverbankcms page unpublish about
+```
+
+### page get
+
+Retrieve a single page with its blocks.
+
+```bash
+riverbankcms page get <identifier>
+riverbankcms page get about
+riverbankcms page get about --json
+```
+
+### page list
+
+List all pages.
+
+```bash
+riverbankcms page list
+riverbankcms page list --limit 10 --page 1
+riverbankcms page list --json
+```
+
+---
+
+## Block Commands
+
+Manage blocks within pages.
+
+### block upsert
+
+Create or update a block on a page.
+
+```bash
+# Basic usage
+riverbankcms block upsert <page-id> <block-id> --kind <block-kind> --data '<json>'
+
+# Examples
+riverbankcms block upsert home hero-main \
+  --kind block.hero \
+  --data '{"heading": "Welcome", "subheading": "to our site"}'
+
+# With JSON file
+riverbankcms block upsert home hero-main \
+  --kind block.hero \
+  --file ./hero-content.json
+
+# With position
+riverbankcms block upsert home new-section \
+  --kind block.bodyText \
+  --data '{"content": "<p>Hello</p>"}' \
+  --position 0
+```
+
+**Arguments:**
+- `<page-id>` - Page identifier
+- `<block-id>` - Block identifier (unique within the page)
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--kind <kind>` | Block type (e.g., `block.hero`, `block.bodyText`) |
+| `--data <json>` | Block content as JSON string |
+| `--file <path>` | Path to JSON file with block content |
+| `--position <n>` | Position in the block list (0-indexed) |
+
+### block reorder
+
+Reorder blocks on a page.
+
+```bash
+riverbankcms block reorder <page-id> <block-id-1> <block-id-2> ...
+
+# Example: Put hero first, then intro, then features
+riverbankcms block reorder home hero-main intro-text features-grid
+```
+
+### block get
+
+Retrieve a specific block.
+
+```bash
+riverbankcms block get <page-id> <block-id>
+riverbankcms block get home hero-main
+riverbankcms block get home hero-main --json
+```
+
+### block list
+
+List all blocks on a page.
+
+```bash
+riverbankcms block list <page-id>
+riverbankcms block list home
+riverbankcms block list home --json
+```
+
+---
+
+## Navigation Commands
+
+Manage navigation menus.
+
+### navigation upsert
+
+Create or update a navigation menu.
+
+```bash
+# With inline JSON
+riverbankcms navigation upsert <menu-name> --data '[{"label": "Home", "url": "/"}]'
+
+# With JSON file
+riverbankcms navigation upsert main --file ./main-nav.json
+```
+
+**Example menu structure:**
+
+```json
+[
+  { "label": "Home", "url": "/" },
+  { "label": "About", "url": "/about" },
+  {
+    "label": "Products",
+    "url": "/products",
+    "children": [
+      { "label": "Category A", "url": "/products/a" },
+      { "label": "Category B", "url": "/products/b" }
+    ]
+  }
+]
+```
+
+### navigation get
+
+Retrieve a navigation menu.
+
+```bash
+riverbankcms navigation get <menu-name>
+riverbankcms navigation get main
+riverbankcms navigation get main --json
+```
+
+### navigation list
+
+List all navigation menus.
+
+```bash
+riverbankcms navigation list
+riverbankcms navigation list --json
+```
+
+---
+
+## Delete Commands
+
+Delete content from the CMS.
+
+### delete entry
+
+Delete an entry.
+
+```bash
+riverbankcms delete entry <type> <identifier> --yes
+riverbankcms delete entry blog-post old-post --yes
+```
+
+### delete block
+
+Delete a block from a page.
+
+```bash
+riverbankcms delete block <page-id> <block-id> --yes
+riverbankcms delete block home old-section --yes
+```
+
+**Note:** The `--yes` flag is required to confirm deletion.
+
+---
+
+## Utility Commands
+
+### preview
+
+Render a block preview.
+
+```bash
+# Print HTML to terminal
+riverbankcms preview <kind> --data '<json>'
+
+# Open in browser
+riverbankcms preview block.hero --data '{"heading": "Test"}' --open
+
+# Capture screenshot
+riverbankcms preview block.hero --data '{"heading": "Test"}' --screenshot
+
+# With custom CSS
+riverbankcms preview block.hero --data '...' --css ./styles.css
+
+# From JSON file
+riverbankcms preview block.hero --file ./hero-data.json
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--data <json>` | Block content as JSON |
+| `--file <path>` | Path to JSON file |
+| `--terminal` | Print HTML to terminal (default) |
+| `--open` | Open in browser |
+| `--screenshot` | Capture screenshot |
+| `--output <path>` | Screenshot output path |
+| `--css <paths...>` | Additional CSS files |
+| `--validation <mode>` | `strict` or `lenient` |
+| `--preview-stage <stage>` | `published` or `preview` |
+
+### identifiers backfill
+
+Generate identifiers for content created before the SDK.
+
+```bash
+riverbankcms identifiers backfill
+riverbankcms identifiers backfill --remote
+```
+
+Use this when migrating existing content to use SDK identifiers.
+
+### init-docs
+
+Scaffold agent documentation (this command).
+
+```bash
+riverbankcms init-docs
+riverbankcms init-docs --path ./custom-path
+riverbankcms init-docs --config ./riverbank.config.ts
+```
+
+---
+
+## Common Patterns
+
+### Creating New Content
+
+```bash
+# 1. Pull latest
+riverbankcms pull
+
+# 2. Create entry
+riverbankcms entry upsert blog-post new-post --data '{"title": "New Post"}'
+
+# 3. Create page
+riverbankcms page upsert new-page --title "New Page" --path /new-page
+
+# 4. Add blocks
+riverbankcms block upsert new-page hero --kind block.hero --data '{"heading": "Welcome"}'
+riverbankcms block upsert new-page body --kind block.bodyText --data '{"content": "<p>...</p>"}'
+
+# 5. Preview
+riverbankcms preview block.hero --data '{"heading": "Welcome"}' --open
+
+# 6. Publish
+riverbankcms page publish new-page
+```
+
+### Updating Existing Content
+
+```bash
+# 1. Pull latest
+riverbankcms pull
+
+# 2. Edit local JSON files in ./content/
+# ... make changes ...
+
+# 3. Preview changes
+riverbankcms push --dry-run
+
+# 4. Push changes
+riverbankcms push
+```
+
+### Agent-Friendly JSON Output
+
+```bash
+# Get entry list as JSON
+riverbankcms entry list blog-post --json
+
+# Preview push diff as JSON
+riverbankcms push --dry-run --json-diff=summary
+
+# Get page with blocks as JSON
+riverbankcms page get home --json
+```
+
+### Working with Production
+
+```bash
+# Pull from production
+riverbankcms pull --remote
+
+# Preview production push
+riverbankcms push --remote --dry-run
+
+# Push to production (requires confirmation)
+riverbankcms push --remote --yes
+```