Create Custom
Project Detection Plugins

1 Getting Started

XEngine plugins are JSON files that define how to detect projects and provide custom actions. They're secure, easy to create, and require no coding knowledge.

To create a plugin, you'll need:

• A text editor (any will do)
• Knowledge of the project structure you want to detect
• Basic understanding of JSON syntax

2 Plugin Structure

Every plugin must contain a manifest and detection object. Optional sections include metadata, actions, and package managers.

// Basic plugin structure
{
  "manifest": {
    "id": "com.example.myplugin",
    "name": "My Framework Plugin",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "Detects My Framework projects",
    "language": "javascript",
    "icon": "⚡"
  },
  "detection": {
    // Detection rules go here
  },
  "metadata": { /* optional */ },
  "actions": [ /* optional */ ],
  "packageManagers": [ /* optional */ ]
}

Manifest Fields

3 Detection Rules

Detection rules tell XEngine how to identify your project type. You can detect by file existence, file content patterns, or a combination of both.

File-Based Detection

Detect projects by checking for specific files or directories:

"detection": {
  "files": [
    {
      "name": "package.json",
      "type": "file",
      "required": true
    },
    {
      "name": "src",
      "type": "directory",
      "required": false
    }
  ]
}

Pattern-Based Detection

Detect projects by matching patterns in file contents:

"detection": {
  "patterns": [
    {
      "file": "composer.json",
      "jsonPath": "$.require['laravel/framework']"
    },
    {
      "file": "package.json",
      "regex": "\"react\"\\s*:"
    },
    {
      "file": ".env.example",
      "exists": true
    }
  ]
}

Confidence Scoring

Control how confident the detection is with base scores and bonus points:

"detection": {
  "confidence": {
    "base": 50,
    "bonus": [
      {
        "condition": "file:vendor/laravel/framework",
        "points": 30
      },
      {
        "condition": "file:artisan",
        "points": 20
      }
    ]
  }
}

4 Version Detection

Automatically detect the version of frameworks or tools in your project using JSONPath expressions or regex patterns.

"metadata": {
  "versionDetection": [
    {
      "source": "composer.lock",
      "path": "$.packages[?(@.name == 'laravel/framework')].version",
      "transform": "removeVersionPrefix"
    },
    {
      "source": "package.json",
      "path": "$.dependencies.react"
    }
  ]
}

5 Custom Actions

Define custom actions that appear in the Project Panel. Actions can execute single commands or multiple commands based on conditions.

"actions": [
  {
    "id": "run-migrations",
    "label": "Run Migrations",
    "icon": "🗄️",
    "command": "php artisan migrate"
  },
  {
    "id": "install-and-build",
    "label": "Install & Build",
    "commands": [
      {
        "packageManager": "npm",
        "command": "npm install"
      },
      {
        "command": "npm run build",
        "optional": true
      }
    ],
    "condition": "packageManager:npm"
  }
]

6 Package Manager Integration

Define custom package managers that integrate with XEngine's package management system. These will appear in the Project Panel with full install/update/uninstall capabilities.

"packageManagers": [
  {
    "id": "my-custom-pm",
    "name": "My Package Manager",
    "icon": "📦",
    "lockFile": "my-lock.json",
    "manifestFile": "my-manifest.json",
    "installCommand": "my-pm install {package}@{version}",
    "uninstallCommand": "my-pm remove {package}",
    "updateCommand": "my-pm update {package}"
  }
]

7 Complete Example

Here's a complete plugin example for a Laravel-like framework:

{
  "manifest": {
    "id": "com.example.laravel-detector",
    "name": "Laravel Framework Detector",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "Detects Laravel PHP framework projects",
    "language": "php",
    "icon": "🔴"
  },
  "detection": {
    "files": [
      { "name": "artisan", "required": true },
      { "name": "composer.json", "required": true }
    ],
    "patterns": [
      {
        "file": "composer.json",
        "jsonPath": "$.require['laravel/framework']"
      }
    ],
    "confidence": {
      "base": 60,
      "bonus": [
        { "condition": "file:vendor/laravel", "points": 30 },
        { "condition": "file:app/Http", "points": 10 }
      ]
    }
  },
  "metadata": {
    "versionDetection": [
      {
        "source": "composer.lock",
        "path": "$.packages[?(@.name == 'laravel/framework')].version"
      }
    ],
    "packageManagers": ["composer", "npm"],
    "framework": "Laravel"
  },
  "actions": [
    {
      "id": "artisan-serve",
      "label": "Start Dev Server",
      "icon": "🚀",
      "command": "php artisan serve"
    },
    {
      "id": "run-migrations",
      "label": "Run Migrations",
      "command": "php artisan migrate"
    }
  ]
}

8 Installation & Distribution

Installing Plugins

You can install plugins through multiple methods:

• From File: Browse and select a plugin JSON file from your computer
• From URL: Provide a direct URL to a plugin JSON file
• From GitHub: Install directly from a GitHub repository
• Create New: Use the built-in wizard to create a basic plugin

Plugin Manager

Access the Plugin Manager from the toolbar (🔌 icon) in XEngine Terminal. Here you can:

• View all installed plugins
• Enable or disable plugins
• Delete plugins
• Install new plugins
• View plugin details

Sharing Your Plugin

To share your plugin with others:

1. Host your plugin JSON file on a web server or GitHub
2. Ensure the file is accessible via HTTP/HTTPS
3. Share the URL with users
4. Users can install it using the "Install from URL" option