decoupled-cli 2.8.0 → 2.9.0

package/examples/FORMAT-REFERENCE.md

@@ -0,0 +1,204 @@
+# Content Import JSON Format Reference
+
+## ⚠️ CRITICAL FORMAT REQUIREMENTS
+
+When importing content via the `import_content` MCP tool or API, you MUST use this exact format:
+
+### Model Array Format
+
+**✅ CORRECT:**
+```json
+{
+  "model": [
+    {
+      "bundle": "article",          // ✓ Use "bundle" key (NOT "type")
+      "label": "Article",
+      "description": "News articles",
+      "fields": [
+        {
+          "id": "summary",            // ✓ Use "id" for field machine name
+          "type": "text",
+          "label": "Summary"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**❌ WRONG:**
+```json
+{
+  "model": [
+    {
+      "type": "article",              // ❌ WRONG - will cause NULL ID error
+      "label": "Article",
+      "fields": [
+        {
+          "name": "summary",          // ❌ Use "id" not "name"
+          "type": "text"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Content Array Format
+
+**✅ CORRECT:**
+```json
+{
+  "content": [
+    {
+      "type": "node.article",         // ✓ Format: "node.bundle_name"
+      "id": "article1",               // ✓ Required unique ID
+      "values": {                     // ✓ Wrap fields in "values" object
+        "title": "My First Article",
+        "summary": "This is a summary"
+      }
+    }
+  ]
+}
+```
+
+**❌ WRONG:**
+```json
+{
+  "content": [
+    {
+      "type": "article",              // ❌ Missing "node." prefix
+      "title": "My Article",          // ❌ Fields not wrapped in "values"
+      "summary": "Summary"
+    }
+  ]
+}
+```
+
+## Complete Working Example
+
+```json
+{
+  "model": [
+    {
+      "bundle": "blog_post",
+      "label": "Blog Post",
+      "description": "Blog articles with author and date",
+      "fields": [
+        {
+          "id": "author",
+          "type": "string",
+          "label": "Author Name"
+        },
+        {
+          "id": "published_date",
+          "type": "datetime",
+          "label": "Published Date"
+        },
+        {
+          "id": "content",
+          "type": "text",
+          "label": "Post Content"
+        }
+      ]
+    }
+  ],
+  "content": [
+    {
+      "type": "node.blog_post",
+      "id": "post1",
+      "values": {
+        "title": "Welcome to My Blog",
+        "author": "John Doe",
+        "published_date": "2026-01-19",
+        "content": "This is my first blog post!"
+      }
+    },
+    {
+      "type": "node.blog_post",
+      "id": "post2",
+      "values": {
+        "title": "Getting Started with Drupal",
+        "author": "Jane Smith",
+        "published_date": "2026-01-20",
+        "content": "Drupal is a powerful CMS..."
+      }
+    }
+  ]
+}
+```
+
+## Field Types Reference
+
+Common field types you can use in the `"type"` field:
+
+- `"string"` - Short text (max 255 chars)
+- `"text"` - Long text with HTML formatting
+- `"datetime"` - Date and time (ISO 8601 format: "2026-01-19")
+- `"bool"` - Boolean true/false
+- `"image"` - Single image upload
+- `"image[]"` - Multiple images
+- `"string[]"` - Multiple string values
+- `"term(vocabulary_name)[]"` - Taxonomy term references
+- `"paragraph(bundle_name)[]"` - Paragraph entity references
+
+## Common Errors and Fixes
+
+### Error: "Cannot load the node_type entity with NULL ID"
+
+**Cause:** Model uses `"type"` instead of `"bundle"`
+
+**Fix:**
+```json
+// ❌ Wrong
+{"model": [{"type": "article", ...}]}
+
+// ✅ Correct
+{"model": [{"bundle": "article", ...}]}
+```
+
+### Error: "Failed to authenticate with Drupal site"
+
+**Actual Cause:** This error message is misleading - it usually means your JSON format is wrong, not an authentication issue.
+
+**Fix:** Check that:
+1. Model uses `"bundle"` key
+2. Content uses `"type": "node.bundle_name"` format
+3. Content has `"id"` and `"values"` wrapper
+
+## Entity Types
+
+### Nodes (Default)
+```json
+{
+  "model": [{"bundle": "article", "label": "Article", "fields": [...]}],
+  "content": [{"type": "node.article", "id": "a1", "values": {...}}]
+}
+```
+
+### Paragraphs
+```json
+{
+  "model": [
+    {
+      "entity": "paragraph",          // ✓ Specify entity type
+      "bundle": "text_block",
+      "label": "Text Block",
+      "fields": [...]
+    }
+  ],
+  "content": [
+    {
+      "type": "paragraph.text_block",  // ✓ Format: "paragraph.bundle"
+      "id": "block1",
+      "values": {...}
+    }
+  ]
+}
+```
+
+## See Also
+
+- `cli/examples/content-import-sample.json` - Comprehensive field type examples
+- `cli/examples/church-starter.json` - Real-world church website example
+- `cli/examples/helloworld-import.json` - Simple getting started example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decoupled-cli",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Command-line interface for managing Decoupled Drupal spaces, deploying content, and automating workflows. Features content import, space management, and CI/CD integration.",
   "main": "dist/index.js",
   "bin": {