@trajendran/commerce-extensibility-migration-tools

v4.0.0

Published

5 days ago

Comprehensive MCP server and Cursor rules for Adobe Commerce App Builder development - supports both migration from PaaS and greenfield development with GitHub integration, quality gates, and Adobe sample alignment

Downloads

Adobe Commerce App Builder Development Tools

MCP server and Cursor rules for Adobe Commerce App Builder development - supports both migration from PaaS and greenfield development.

Version 4.0.0 | Changelog | npm

🎯 What This Does

Guides you through Adobe Commerce App Builder development with:

Dual Mode Support - Migration from PaaS OR greenfield development
Dual Mode Support - Migration from PaaS OR greenfield development
Clean 4-Phase Workflow - Structured approach for BOTH migration and greenfield
Type-Specific Phase Workflows - 4 dedicated workflows for migration, 4 for greenfield
Conditional Rule Loading - Rules load only when needed (applyWhen keywords)
Single Document (REQUIREMENTS.md) - One source of truth for both types
Strict Phase Gates - Non-negotiable transitions, prevents mistakes
Implementation Approach Selection - Choose detailed plan or direct implementation
Optional Phase 0 (Migration) - Pre-discovery before requirements
Quality Gates - Linting and validation integrated in Phase 4
Adobe Sample Alignment - Ensure code matches official patterns (>90%)
12 MCP Tools - Analysis, validation, and deployment automation
27 Specialized Cursor Rules - 8 phase workflows + 19 specialized guides
Universal Support - Works for ALL types (Admin UI, Events, Cron, Payment, etc.)

⚡ Setup

Option 1: Analysis Only (5 min)

Generate migration documentation without building anything yet.

# In your Adobe Commerce project
npm install --save-dev @trajendran/commerce-extensibility-migration-tools

Configure .cursor/mcp.json:

{
  "mcpServers": {
    "commerce-migration": {
      "command": "node",
      "args": ["node_modules/@trajendran/commerce-extensibility-migration-tools/index.js"]
    }
  }
}

Ready! Use analysis prompts below.

Option 2: Full Implementation (30 min)

Ready to build the App Builder application.

# Clone starter kit
git clone https://github.com/adobe/commerce-integration-starter-kit.git my-app
cd my-app
npm install

# Install migration tools
npm install --save-dev @trajendran/commerce-extensibility-migration-tools

Configure .cursor/mcp.json:

{
  "mcpServers": {
    "commerce-migration": {
      "command": "node",
      "args": ["node_modules/@trajendran/commerce-extensibility-migration-tools/index.js"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

Configure .env:

AIO_runtime_namespace=your-namespace
AIO_runtime_auth=your-auth-token
COMMERCE_BASE_URL=https://your-store.com

Ready! Use implementation prompts below.

💬 Prompts

Using the Streamlined Prompt Template

Focus on WHAT you need (business requirements), not HOW to build it (MCP tools discover patterns automatically).

Supports TWO modes:

Migration: From existing PaaS module to App Builder (8 questions in Phase 1)
Greenfield: Build new App Builder application from scratch (7 questions in Phase 1)

Key Point: You provide business requirements; tools automatically find Adobe samples and patterns.

Questions are now built into Phase 1 workflow - no separate template needed!

🔄 Migration Examples

Example 1: Hybrid Extension Migration (Product Import)

Project: Product Import System
Type: Migration
Mode: analysis_and_implementation
Module Path: app/code/Acme/ProductImport

What it does:
Imports products from external ERP system with Admin UI to manage attribute mappings.

Business Goal:
- Handle 1000 products/minute asynchronously
- Admin UI for managing attribute mappings (external ↔ Commerce)
- Public REST API for external systems
- Non-blocking import process

Who uses it:
- External backend systems (pushing product data)
- Adobe Commerce admins (managing mappings)

Data:
- Products (SKU, name, price, attributes)
- Attribute mappings (field transformations)
- Import jobs (status, errors)

Integrations:
- External ERP system (product feed)

Constraints:
- Performance: 1000 products/minute
- Response time: < 5 seconds for API calls
- Security: API key authentication

Timeline: 3 weeks
Approach: Full migration

Note: MCP tools will automatically find relevant Adobe samples and patterns.

Example 2: Event Consumer Migration

Project: Order Notification System
Type: Migration
Mode: analysis_and_implementation
Module Path: app/code/Acme/OrderNotification

What it does:
Sends order data to external fulfillment system when order is placed.

Business Goal:
- Auto-send orders to fulfillment system
- Must be asynchronous (non-blocking)
- Retry on failure (3 attempts)
- Log all processing for audit

Who uses it:
- Commerce (emits order placement events)
- Fulfillment ERP (receives order data)

Data:
- Order details (items, addresses, payment)

Integrations:
- External fulfillment API (https://erp.example.com/api)

Constraints:
- Process within 5 seconds
- Security: Validate event signatures
- Retry: Exponential backoff (1s, 2s, 4s)

Timeline: 1 week
Risk Tolerance: Medium

🆕 Greenfield Examples

Example 3: Event Consumer (New)

Project: Warehouse Inventory Sync
Type: Greenfield
Mode: analysis_and_implementation

Application Purpose:
Real-time inventory synchronization from Commerce to external warehouse.

Business Goal:
- Listen to inventory update events
- Transform and send to warehouse API
- Handle retries automatically

Who uses it:
- Commerce (emits inventory events)
- Warehouse system (receives updates)

Data:
- Inventory changes (SKU, quantity, location)

Integrations:
- Warehouse API (REST)

Constraints:
- Process within 3 seconds
- Retry 3 times on failure

Timeline: 1 week

Example 4: Scheduled Action (New)

Project: Daily Sales Report
Type: Greenfield
Mode: analysis_and_implementation

Application Purpose:
Daily sales data aggregation with automated email delivery.

Business Goal:
- Run daily at 6 AM UTC
- Aggregate previous day sales
- Generate PDF report
- Email to management

Who uses it:
- Scheduled trigger (automated)
- Management team (recipients)

Data:
- Sales transactions

Integrations:
- Email service (SendGrid)

Timeline: 1 week

📊 Migration vs Greenfield

| Aspect | Migration | Greenfield | |--------|-----------|------------| | Document | REQUIREMENTS.md | REQUIREMENTS.md ✅ Same! | | Workflow | 4 phases (+optional Phase 0) | 4 phases | | Phase 0 | ✅ Optional (pre-discovery) | ❌ Not applicable | | Phase 1 Questions | 8 migration-specific | 7 greenfield-specific | | Module Analysis | ✅ analyze_module tool | ❌ Not applicable | | Phases 2-4 | ✅ Same universal workflow | ✅ Same universal workflow | | Quality Gates | ✅ Phase 4 | ✅ Phase 4 | | Sample Alignment | ✅ >90% target | ✅ >90% target |

Both use same 4-phase pattern, quality gates, and Adobe sample alignment!

Quick Prompts (Analysis Only)

Migration analysis:

Analyze app/code/Vendor/OrderExport for App Builder migration.
Project Type: Migration
Generate MIGRATION_REQUIREMENTS.md. Do not generate code yet.

Greenfield requirements:

Build real-time order notification system for external fulfillment.
Project Type: Greenfield
Generate REQUIREMENTS.md with architecture recommendations.

Archived: Migration-Only Examples

Old Example 3: Scheduled Action Migration

Project: Daily Inventory Sync
Type: Migration
Mode: analysis_and_implementation
Module Path: app/code/Acme/InventorySync

What it does:
Syncs inventory levels from ERP to Commerce daily.

Business Goal:
- Run daily at 2 AM UTC
- Process 10,000 SKUs
- Send completion notification
- Must be idempotent (safe to re-run)

Who uses it:
- Scheduled trigger (automated)

Data:
- Inventory levels (SKU, quantity)

Integrations:
- SAP ERP (inventory API)

Constraints:
- Complete within 30 minutes
- Continue on individual SKU failures
- Log all errors

Timeline: 2 weeks (1 week dev + 1 week testing)
Risk Tolerance: Medium

Validation Prompts

Before deployment:

Validate my project before deployment:
1. Check file structure
2. Verify path resolution
3. Check for duplicate files
4. Run pre-deployment validation

Only deploy if all checks pass.

Fix path issues:

My actions aren't found during deployment. 
Run verify-path-resolution on my config file to show where files should actually be.

🛠️ Key Features

Phase 0 Tools (Prevent Common Mistakes)

| Tool | Purpose | When | |------|---------|------| | validate-file-structure | Check structure before coding | Before creating files | | verify-path-resolution | Show where files should go | Before creating actions | | create-architecture-doc | Generate structure docs | After analyzing samples | | validate-pre-deployment | Comprehensive checks | Before every deploy |

Analysis Tools

| Tool | Purpose | |------|---------| | analyze-module | Analyze PaaS module complexity | | list-all-modules | List all custom modules | | get-migration-status | Track migration progress | | recommend-implementation | AI-powered strategy recommendations |

GitHub Integration Tools

| Tool | Purpose | |------|---------| | analyze-github-sample | Analyze Adobe Commerce samples | | search-samples-by-pattern | Find relevant samples | | compare-with-sample | Compare with official patterns | | get-migration-documentation | Component-specific docs |

Universal Support

Works for ALL migration types:

✅ Admin UI Extensions (grids, menus, forms)
✅ Runtime Actions (controllers)
✅ Event Consumers (observers)
✅ Scheduled Actions (cron jobs)
✅ Payment Integrations
✅ Shipping Integrations
✅ API Mesh (plugins)

Tools automatically detect whether you're building admin-ui-sdk or app-builder extensions.

📋 Migration Patterns

| PaaS Component | App Builder Pattern | Extension Type | |----------------|---------------------|----------------| | Controllers | Runtime Actions | app-builder | | Observers | I/O Events Consumers | app-builder | | Cron Jobs | Scheduled Actions | app-builder | | Admin Grids/Forms | Admin UI SDK | admin-ui-sdk | | Payment Methods | Payment Actions | app-builder | | Shipping Carriers | Shipping Actions | app-builder | | Plugins | API Mesh Resolvers | app-builder |

🎯 Workflow

Clean 4-Phase Universal Workflow (Both Migration & Greenfield):

[Optional Phase 0: Pre-Discovery] (Migration Only)
  → User can choose to execute or skip
  → Search Adobe samples
  → Analyze sample structure
  → Create ARCHITECTURE.md
  → Saves 90+ minutes if executed

Phase 1: Requirements & Clarification (20-60 min)
  → Detect project type (migration vs greenfield)
  → Create REQUIREMENTS.md (single document for both types)
  → Ask type-specific questions:
    • Migration: 8 questions (module path, components, etc.)
    • Greenfield: 7 questions (events, integrations, etc.)
  → Document all requirements
  → Marker: "Phase 1: Complete ✅"

Phase 2: Architectural Planning (30-45 min)
  → Present requirements for review
  → Present detailed architecture plan
  → Get explicit user approval
  → Marker: "Phase 2: Complete ✅"

Phase 3: Implementation Approach Selection (5-10 min)
  → Present Option A (Detailed Plan) vs Option B (Direct)
  → User selects approach
  → Document selection
  → Marker: "Phase 3: Implementation Approach Selected: [A/B]"

Phase 4: Implementation & Code Generation (varies)
  → Generate code per selected approach
  → ✅ Apply quality gates (linting, sample alignment)
  → ✅ Validate security and paths
  → Provide deployment readiness summary
  → Marker: "Phase 4: Complete ✅"

Key Features:

🔄 Conditional Loading - Rules load only when phase is active
📄 Single Document - REQUIREMENTS.md for both types
🚦 Strict Phase Gates - Cannot skip phases
🎯 Self-Validation - Each phase validates before proceeding
⚡ Efficient - Based on proven greenfield tool pattern
🔍 Quality Gates - Integrated in Phase 4

Structure:

main-orchestrator.mdc - Project type + phase detection
development-workflow-phase1.mdc - Universal Phase 1 (applyWhen)
development-workflow-phase2.mdc - Universal Phase 2 (applyWhen)
development-workflow-phase3.mdc - Universal Phase 3 (applyWhen)
development-workflow-phase4.mdc - Universal Phase 4 (applyWhen)
migration-phase-0-discovery.mdc - Optional Phase 0 (migration only)

📚 Documentation

Prompt Examples - Comprehensive prompt guide for all scenarios
Changelog - Version history and release notes

Technical Docs (Optional)

🚀 Quick Examples

Just Getting Started?

Week 1: Analyze

# In your PaaS project (5 min setup)
npm install --save-dev @trajendran/commerce-extensibility-migration-tools

Prompt: "Analyze app/code/Vendor/Module for migration"
Output: MIGRATION_REQUIREMENTS.md

Week 2: Implement

# Clone starter kit (30 min setup)
git clone starter-kit
npm install migration-tools

Prompt: "Migrate [module] with Phase 0 discovery"
Output: Working App Builder app

Already Have Requirements?

git clone starter-kit && cd starter-kit
npm install @trajendran/commerce-extensibility-migration-tools
# Configure .cursor/mcp.json and .env

Prompt: "Implement approved migration with Phase 0"

🔑 Key Innovation: Phase 0

Problem: Developers started coding before understanding structure → files in wrong locations → 5+ redeployments

Solution: Phase 0 discovery before coding → correct structure from start → 1 deployment

Real Impact:

❌ Before: Code → Deploy → Error → Fix → Deploy... (2+ hours wasted)
✅ After: Phase 0 → Code → Deploy once (saves 90 minutes)

💡 Tips

Use the structured prompt template:

Start every migration with the prompt template:
- File: rules/Cursor/migration-prompt-template.mdc
- Gather ALL requirements upfront
- Reduces back-and-forth iterations
- Ensures nothing is missed

See Example 1-4 in Prompts section above.

Always use Phase 0 for new migrations:

Before coding, complete Phase 0:
1. Search Adobe samples (search-samples-by-pattern)
2. Analyze structure (analyze-github-sample)
3. Verify paths (verify-path-resolution)
4. Validate structure (validate-file-structure)
5. Create ARCHITECTURE.md (create-architecture-doc)

This saves 90+ minutes of rework later!

Apply quality gates during implementation:

After generating EACH component:
1. Run ESLint --fix
2. Validate against Adobe sample (compare-with-sample)
3. Fix issues immediately
4. Don't proceed until linting passes

Before deployment:
- validate-pre-deployment (must pass)
- All tests pass (100%)
- Security scan clean
- Sample alignment >90%

Modular workflow files for better organization:

Phase-specific files:
- migration-prompt-template.mdc (requirements template)
- migration-phase-0-discovery.mdc (pre-implementation)
- migration-phase-1-analysis.mdc (analysis)
- migration-phase-2-planning.mdc (architecture)
- migration-code-quality.mdc (linting/validation)
- migration-adobe-sample-alignment.mdc (sample validation)

Each phase has its own focused file.

🐛 Support

📄 License

Apache-2.0

Built for Adobe Commerce developers migrating from PaaS to App Builder 🚀