decoupled-cli 2.0.2 → 2.1.0

package/examples/CLAUDE.md

@@ -5,7 +5,7 @@ This document provides Claude Code with comprehensive instructions for building
 ## Project Overview
 
 **Architecture**: Headless Drupal backend with Next.js frontend
-**Backend**: Drupal 11 with GraphQL Compose and DCloud Import API
+**Backend**: Drupal 11 with GraphQL Compose and DC Import API
 **Frontend**: Next.js 15 with TypeScript, Tailwind CSS, and Apollo GraphQL
 **Environment**: DDEV local development
 
@@ -18,29 +18,29 @@ This document provides Claude Code with comprehensive instructions for building
 - `DRUPAL_REVALIDATE_SECRET` - Secret for on-demand revalidation
 - `NODE_TLS_REJECT_UNAUTHORIZED=0` - Allow self-signed certificates (development)
 
-## DCloud CLI Setup
+## DC CLI Setup
 
 **First-time CLI setup:**
 ```bash
-# 1. Install dcloud-cli locally (if not already present in package.json)
-npm install --save-dev dcloud-cli
+# 1. Install decoupled-cli locally (if not already present in package.json)
+npm install --save-dev decoupled-cli
 
 # 2. Configure authentication - you have two options:
 
 # Option A: Use OAuth with your existing Drupal credentials (recommended for local development)
-npx dcloud-cli auth oauth
+npx decoupled-cli auth oauth
 
 # Option B: Use personal access token (for production/remote deployments)
-npx dcloud-cli auth login
+npx decoupled-cli auth login
 
 # 3. Set your default space for content imports (optional but recommended)
-npx dcloud-cli spaces use <space_id>
+npx decoupled-cli spaces use <space_id>
 
 # 4. Verify authentication and space setup
-npx dcloud-cli spaces current
+npx decoupled-cli spaces current
 ```
 
-**OAuth Prerequisites (for `dcloud auth oauth`):**
+**OAuth Prerequisites (for `decoupled-cli auth oauth`):**
 Your `.env.local` must contain:
 - `NEXT_PUBLIC_DRUPAL_BASE_URL=https://your-space.decoupled.io`
 - `DRUPAL_CLIENT_ID=your_oauth_client_id`
@@ -48,12 +48,12 @@ Your `.env.local` must contain:
 
 **Authentication Method Differences:**
 - **OAuth** → Works with your Drupal site API (content import, Drupal operations)
-- **Personal Access Token** → Works with DrupalCloud platform API (spaces, users, organizations)
+- **Personal Access Token** → Works with Decoupled Drupal platform API (spaces, users, organizations)
 
 **If CLI is not available locally:**
-- For projects with dcloud-cli in package.json: Run `npm install` then use `npx dcloud-cli`
-- For development: `cd cli && npm install && npm run build && npm link` then use `dcloud`
-- Always prefer using `npx dcloud-cli` for consistency and local package management
+- For projects with decoupled-cli in package.json: Run `npm install` then use `npx decoupled-cli`
+- For development: `cd cli && npm install && npm run build && npm link` then use `decoupled-cli`
+- Always prefer using `npx decoupled-cli` for consistency and local package management
 
 ## End-to-End Development Workflow
 
@@ -73,9 +73,9 @@ Use OAuth authentication for direct Drupal content import, then frontend develop
 
 **Create a todo list for tracking progress:**
 ```markdown
-1. Verify DCloud CLI authentication (npx dcloud-cli auth status)
-2. Create DCloud Import JSON for [content_type]
-3. Import content type and sample content to Drupal (npx dcloud-cli content import)
+1. Verify DC CLI authentication (npx decoupled-cli auth status)
+2. Create DC Import JSON for [content_type]
+3. Import content type and sample content to Drupal (npx decoupled-cli content import)
 4. **CRITICAL**: Run schema generation (`npm run generate-schema`) to update GraphQL schema
 5. Create TypeScript types and GraphQL queries
 6. Build frontend components ([ContentCard], [ContentRenderer])
@@ -84,12 +84,12 @@ Use OAuth authentication for direct Drupal content import, then frontend develop
 9. Validate end-to-end functionality
 ```
 
-**Legacy Platform Workflow (PAT + DrupalCloud Platform):**
+**Legacy Platform Workflow (PAT + Decoupled Drupal Platform):**
 ```markdown
-1. Verify DCloud CLI authentication (npx dcloud-cli auth status)
-2. Set default space if needed (npx dcloud-cli spaces use <id>)
-3. Create DCloud Import JSON for [content_type]
-4. Import content type and sample content via platform (npx dcloud-cli spaces content-import)
+1. Verify DC CLI authentication (npx decoupled-cli auth status)
+2. Set default space if needed (npx decoupled-cli spaces use <id>)
+3. Create DC Import JSON for [content_type]
+4. Import content type and sample content via platform (npx decoupled-cli spaces content-import)
 5. **CRITICAL**: Run schema generation (`npm run generate-schema`) to update GraphQL schema
 6. Create TypeScript types and GraphQL queries
 7. Build frontend components ([ContentCard], [ContentRenderer])
@@ -103,23 +103,23 @@ Use OAuth authentication for direct Drupal content import, then frontend develop
 **ALWAYS start by verifying CLI setup:**
 ```bash
 # Check if CLI is authenticated
-npx dcloud-cli auth status
+npx decoupled-cli auth status
 
 # If not authenticated, choose authentication method:
 # For local development with Drupal OAuth:
-npx dcloud-cli auth oauth
+npx decoupled-cli auth oauth
 
 # For production with personal access token:
-npx dcloud-cli auth login
+npx decoupled-cli auth login
 
 # List available spaces and set default
-npx dcloud-cli spaces list
-npx dcloud-cli spaces use <space_id>
+npx decoupled-cli spaces list
+npx decoupled-cli spaces use <space_id>
 ```
 
 **If CLI authentication fails:**
 - For OAuth: Verify `.env.local` contains `NEXT_PUBLIC_DRUPAL_BASE_URL`, `DRUPAL_CLIENT_ID`, `DRUPAL_CLIENT_SECRET`
-- For personal tokens: Check that DCloud platform is accessible
+- For personal tokens: Check that DC platform is accessible
 - Ensure user has proper permissions for the operations you're trying to perform
 
 **Important: Command Availability by Authentication Method**
@@ -127,11 +127,11 @@ npx dcloud-cli spaces use <space_id>
 - **PAT-only commands**: `spaces list`, `spaces use`, `usage`, `org info`
 - **Universal commands**: `auth login`, `auth oauth`, `auth test`
 
-### 2. DCloud Import JSON Creation
+### 2. DC Import JSON Creation
 
 **Get example format with CLI:**
 ```bash
-npx dcloud-cli spaces content-import --example > my-content-type.json
+npx decoupled-cli spaces content-import --example > my-content-type.json
 ```
 
 **Use this JSON structure:**
@@ -186,32 +186,32 @@ npx dcloud-cli spaces content-import --example > my-content-type.json
 - **For image fields**: Use full URLs with the Drupal domain from `.env.local`, not relative paths:
   ```json
   "featured_image": {
-    "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+    "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
     "alt": "Description of the image",
     "title": "Image title"
   }
   ```
   Always read the `NEXT_PUBLIC_DRUPAL_BASE_URL` from `.env.local` and use that as the base for image URIs to ensure images load correctly from the Drupal backend.
 
-### 3. Import via DCloud CLI
+### 3. Import via DC CLI
 
 **Import Content Type:**
 ```bash
 # NEW: Import content directly to your Drupal site (OAuth authentication)
-npx dcloud-cli content import --file content-type-import.json
+npx decoupled-cli content import --file content-type-import.json
 
 # Or preview first to see what will be imported
-npx dcloud-cli content import --file content-type-import.json --preview
+npx decoupled-cli content import --file content-type-import.json --preview
 
-# LEGACY: Import via DrupalCloud platform (requires PAT authentication and space setup)
-npx dcloud-cli spaces content-import --file content-type-import.json
-npx dcloud-cli spaces content-import <space_id> --file content-type-import.json
+# LEGACY: Import via Decoupled Drupal platform (requires PAT authentication and space setup)
+npx decoupled-cli spaces content-import --file content-type-import.json
+npx decoupled-cli spaces content-import <space_id> --file content-type-import.json
 ```
 
 **Generate example import file:**
 ```bash
 # Get example import JSON structure (works with both methods)
-npx dcloud-cli content import --example > content-type-import.json
+npx decoupled-cli content import --example > content-type-import.json
 # Then edit the generated file with your content type definition
 ```
 
@@ -220,7 +220,7 @@ npx dcloud-cli content import --example > content-type-import.json
 - Field machine names (auto-generated)
 - Node IDs created
 - GraphQL schema updates
-- **Important**: GraphQL field names may differ from DCloud field IDs (check actual schema)
+- **Important**: GraphQL field names may differ from DC field IDs (check actual schema)
 
 **CRITICAL: Immediately Update GraphQL Schema After Import:**
 ```bash
@@ -500,7 +500,7 @@ npm run dev
 ### 6. Testing Checklist
 
 **Verify each step:**
-- [ ] DCloud import successful with no errors
+- [ ] DC import successful with no errors
 - [ ] GraphQL schema includes new content type
 - [ ] TypeScript types are properly defined
 - [ ] Build process completes without errors
@@ -540,7 +540,7 @@ npm run dev
 ```json
 "product_images": [
   {
-    "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+    "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
     "alt": "Product showcase image",
     "title": "Product Image"
   }
@@ -588,7 +588,7 @@ npm run dev
 **Sample content with image URI:**
 ```json
 "profile_image": {
-  "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+  "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
   "alt": "Team member headshot",
   "title": "Profile Photo"
 }
@@ -617,7 +617,7 @@ npm run dev
 ```json
 "project_images": [
   {
-    "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+    "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
     "alt": "Project screenshot showing main interface",
     "title": "Project Interface"
   }
@@ -628,7 +628,7 @@ npm run dev
 
 ### Common Issues
 
-**1. DCloud Import Fails**
+**1. DC Import Fails**
 - Check OAuth token expiration
 - Verify JSON structure matches `schema/sample.json` format
 - Ensure field IDs don't start with `field_`
@@ -645,15 +645,15 @@ npm run dev
 - Verify GraphQL query syntax
 
 **4. Content Not Displaying**
-- Check GraphQL query field names match Drupal fields (may not match DCloud field IDs)
+- Check GraphQL query field names match Drupal fields (may not match DC field IDs)
 - Verify content was created and published
 - Check query variables and pagination
 - For HTML content showing raw tags, use `dangerouslySetInnerHTML={{ __html: field.processed }}`
 
-**5. GraphQL Schema Not Updated After DCloud Import**
-- **Critical Issue**: DCloud imports create content types successfully but GraphQL schema may not update immediately
+**5. GraphQL Schema Not Updated After DC Import**
+- **Critical Issue**: DC imports create content types successfully but GraphQL schema may not update immediately
 - Content exists in Drupal but `nodeProducts` query returns "field not found" errors
-- This is the most common issue with DCloud imports
+- This is the most common issue with DC imports
 
 **Solution Process**:
 1. Clear Drupal caches (if you have admin access)
@@ -663,7 +663,7 @@ npm run dev
 
 ### Essential Schema Generation Workflow
 
-**CRITICAL**: Always run schema generation after DCloud imports to ensure GraphQL integration works properly.
+**CRITICAL**: Always run schema generation after DC imports to ensure GraphQL integration works properly.
 
 ```bash
 # Generate updated GraphQL schema after content type imports
@@ -677,7 +677,7 @@ This command:
 - Validates that new content types are available in GraphQL
 
 **Add this to your workflow**:
-1. Import content type via DCloud API
+1. Import content type via DC API
 2. **Immediately run**: `npm run generate-schema`
 3. Check generated schema includes your new content type
 4. Test GraphQL queries
@@ -687,37 +687,37 @@ This command:
 
 ```bash
 # Check CLI authentication status
-npx dcloud-cli auth status
+npx decoupled-cli auth status
 
 # OAUTH/DRUPAL COMMANDS:
 # Check content import API status
-npx dcloud-cli content status
+npx decoupled-cli content status
 
 # Preview content import without applying changes
-npx dcloud-cli content import --file your-import.json --preview
+npx decoupled-cli content import --file your-import.json --preview
 
 # Import content to Drupal
-npx dcloud-cli content import --file your-import.json
+npx decoupled-cli content import --file your-import.json
 
 # Generate fresh schema (most important after any import)
 npm run generate-schema
 
-# PAT/PLATFORM COMMANDS (require npx dcloud-cli auth login):
+# PAT/PLATFORM COMMANDS (require npx decoupled-cli auth login):
 # List available spaces
-npx dcloud-cli spaces list
+npx decoupled-cli spaces list
 
 # Check current default space
-npx dcloud-cli spaces current
+npx decoupled-cli spaces current
 
-# Get health status of DCloud platform
-npx dcloud-cli health check
+# Get health status of DC platform
+npx decoupled-cli health check
 
 # Check organization info
-npx dcloud-cli org info
+npx decoupled-cli org info
 
 # Legacy platform content import
-npx dcloud-cli spaces content-import --file your-import.json --preview
-npx dcloud-cli spaces content-import --file your-import.json --json
+npx decoupled-cli spaces content-import --file your-import.json --preview
+npx decoupled-cli spaces content-import --file your-import.json --json
 ```
 
 ## Content Import Command Reference
@@ -726,22 +726,22 @@ npx dcloud-cli spaces content-import --file your-import.json --json
 
 **Check content import API status:**
 ```bash
-npx dcloud-cli content status
+npx decoupled-cli content status
 ```
 
 **Generate example import JSON:**
 ```bash
-npx dcloud-cli content import --example > my-content-type.json
+npx decoupled-cli content import --example > my-content-type.json
 ```
 
 **Preview import (dry run):**
 ```bash
-npx dcloud-cli content import --file my-content-type.json --preview
+npx decoupled-cli content import --file my-content-type.json --preview
 ```
 
 **Import content to Drupal:**
 ```bash
-npx dcloud-cli content import --file my-content-type.json
+npx decoupled-cli content import --file my-content-type.json
 ```
 
 ### Authentication Setup for Content Import
@@ -750,13 +750,13 @@ npx dcloud-cli content import --file my-content-type.json
 ```bash
 # 1. Ensure .env.local has OAuth credentials
 # 2. Set up OAuth profile
-npx dcloud-cli auth oauth
+npx decoupled-cli auth oauth
 
 # 3. Verify it's working
-npx dcloud-cli content status
+npx decoupled-cli content status
 
 # 4. Import content
-npx dcloud-cli content import --file your-content.json
+npx decoupled-cli content import --file your-content.json
 ```
 
 **When to use OAuth vs PAT:**
@@ -774,7 +774,7 @@ npx dcloud-cli content import --file your-content.json
 7. **Include proper TypeScript types** for all data structures
 8. **Test the full user journey** from listing to detail pages
 9. **Use `dangerouslySetInnerHTML`** for processed HTML content from Drupal to avoid raw tag display
-10. **Verify GraphQL field names** match actual schema, not DCloud field IDs
+10. **Verify GraphQL field names** match actual schema, not DC field IDs
 
 ## Success Criteria
 
@@ -792,7 +792,7 @@ A successful end-to-end implementation should:
 
 Based on successful product catalog implementation, here are critical learnings to avoid common pitfalls:
 
-### DCloud Import Format Issues
+### DC Import Format Issues
 
 **Problem**: Field values incorrectly formatted with "field_" prefix
 ```json
@@ -813,14 +813,14 @@ Based on successful product catalog implementation, here are critical learnings
 
 ### GraphQL Field Name Mapping
 
-**Problem**: Assuming GraphQL field names match DCloud field IDs
+**Problem**: Assuming GraphQL field names match DC field IDs
 ```typescript
 // WRONG - Field names may be transformed
-price: string           // DCloud field ID
+price: string           // DC field ID
 fieldPrice: string      // What you might expect in GraphQL
 
 // CORRECT - Check actual schema
-price: string          // Actual GraphQL field name (can match DCloud ID)
+price: string          // Actual GraphQL field name (can match DC ID)
 inStock: boolean       // camelCase transformation
 productImages: object  // snake_case to camelCase
 ```
@@ -829,7 +829,7 @@ productImages: object  // snake_case to camelCase
 
 ### GraphQL Field Value Structure Discovery
 
-**Critical Learning**: GraphQL field values from DCloud imports return as simple types, not objects:
+**Critical Learning**: GraphQL field values from DC imports return as simple types, not objects:
 
 ```typescript
 // WRONG - Assuming field values are objects with .processed
@@ -840,7 +840,7 @@ fieldFeatures?: Array<{
   processed: string
 }>
 
-// CORRECT - DCloud imports create simple value fields
+// CORRECT - DC imports create simple value fields
 price?: string
 features?: string[]
 ```
@@ -953,29 +953,29 @@ npm run dev    # Test in development mode
 
 The most important learning from the product catalog implementation is the **mandatory schema generation step**:
 
-**Problem**: DCloud imports successfully create content types and content, but GraphQL schema doesn't update automatically.
+**Problem**: DC imports successfully create content types and content, but GraphQL schema doesn't update automatically.
 **Symptoms**:
 - `nodeProducts` query returns "field not found" errors
 - Content exists in Drupal but not accessible via GraphQL
 - Route queries work but content type queries fail
 
-**Solution**: **ALWAYS run schema generation immediately after DCloud imports**:
+**Solution**: **ALWAYS run schema generation immediately after DC imports**:
 
 ```bash
-# After any DCloud import, immediately run:
+# After any DC import, immediately run:
 npm run generate-schema
 
 # This step is MANDATORY for GraphQL integration to work
 ```
 
 **Why this is critical**:
-- DCloud API creates Drupal content types but doesn't trigger GraphQL schema rebuilds
+- DC API creates Drupal content types but doesn't trigger GraphQL schema rebuilds
 - The `generate-schema` script performs fresh introspection and updates local schema files
 - Without this step, frontend development will fail with "type not found" errors
 - This step bridges the gap between Drupal content type creation and Next.js GraphQL integration
 
 **Workflow Integration**:
-1. Import via DCloud API ✅
+1. Import via DC API ✅
 2. **Run `npm run generate-schema`** ✅ ← CRITICAL STEP
 3. Verify schema includes new content type ✅
 4. Proceed with frontend development ✅
@@ -984,7 +984,7 @@ This learning transforms the development workflow from "sometimes works" to "rel
 
 ### GraphQL Schema Field Name Discovery
 
-**Critical Process**: Always verify actual GraphQL field names after DCloud import - they may differ from field IDs used in import JSON.
+**Critical Process**: Always verify actual GraphQL field names after DC import - they may differ from field IDs used in import JSON.
 
 **Discovery Method**:
 ```bash
@@ -994,7 +994,7 @@ grep -A 10 -B 5 nodeProducts schema/schema.graphql
 # This shows the actual field names and types available
 ```
 
-**Key Learning**: DCloud field IDs may transform in GraphQL schema:
+**Key Learning**: DC field IDs may transform in GraphQL schema:
 - `in_stock` becomes `inStock` (camelCase)
 - `product_images` becomes `productImages` (camelCase)
 - Simple field types work reliably (string, boolean, string[])
@@ -1048,7 +1048,7 @@ Based on successful product catalog implementation:
 
 **Essential Commands Sequence**:
 ```bash
-# After DCloud import, always run:
+# After DC import, always run:
 npm run generate-schema  # Updates GraphQL schema
 npm run build           # Validates TypeScript and builds
 npm run dev            # Test in development
@@ -1062,9 +1062,9 @@ npm run dev            # Test in development
 
 ### Deployment Field Mapping Reference
 
-**DCloud Import → GraphQL Schema Mapping**:
+**DC Import → GraphQL Schema Mapping**:
 ```json
-// DCloud import format:
+// DC import format:
 {
   "in_stock": true,           // → GraphQL: inStock
   "product_images": [...],    // → GraphQL: productImages