@qelos/plugins-cli 0.0.9 → 0.0.11

package/README.md

@@ -3,11 +3,144 @@
 A command-line interface to help you create and manage your Qelos plugins.
 
 ## Installation
-> npm install -g @qelos/plugins-cli
+
+### Global Installation
+
+Install the CLI globally using npm:
+
+```bash
+npm install -g @qelos/plugins-cli
+```
+
+After installation, the CLI will be available as both `qelos` and `qplay` commands:
+
+```bash
+qelos --version
+qplay --version
+```
+
+### Environment Variables
+
+The CLI requires the following environment variables to connect to your Qelos instance:
+
+- `QELOS_URL` - Your Qelos instance URL (default: `http://localhost:3000`)
+- `QELOS_USERNAME` - Your Qelos username (default: `test@test.com`)
+- `QELOS_PASSWORD` - Your Qelos password (default: `admin`)
+
+You can set these in your shell profile or use a `.env` file:
+
+```bash
+export QELOS_URL=https://your-qelos-instance.com
+export QELOS_USERNAME=your-username
+export QELOS_PASSWORD=your-password
+```
 
 ## Commands
 
 ### Create a new plugin
 
-Basic usage to create new plugin
-> qplay create my-app
+Create a new plugin project:
+
+```bash
+qplay create my-app
+```
+
+### Pull
+
+Pull resources from your Qelos instance to your local filesystem. This allows you to work on components, plugins, integrations, and blueprints locally.
+
+**Syntax:**
+```bash
+qelos pull <type> <path>
+```
+
+**Arguments:**
+- `type` - Type of resource to pull (e.g., `components`, `plugins`, `integrations`, `blueprints`)
+- `path` - Local directory path where resources will be saved
+
+**Example - Pull Components:**
+```bash
+qelos pull components ./my-components
+```
+
+This command will:
+1. Connect to your Qelos instance using the configured credentials
+2. Fetch all components from the instance
+3. Create the target directory if it doesn't exist
+4. Save each component as a `.vue` file using its identifier as the filename
+5. Display progress for each component pulled
+
+**Output:**
+```
+Created directory: ./my-components
+Found 5 components to pull
+Pulled component: header-component
+Pulled component: footer-component
+Pulled component: sidebar-component
+All 5 components pulled to ./my-components
+```
+
+### Push
+
+Push local resources to your Qelos instance. This allows you to update or create components, plugins, integrations, and blueprints from your local filesystem.
+
+**Syntax:**
+```bash
+qelos push <type> <path>
+```
+
+**Arguments:**
+- `type` - Type of resource to push (e.g., `components`, `plugins`, `integrations`, `blueprints`)
+- `path` - Local directory path containing the resources to push
+
+**Example - Push Components:**
+```bash
+qelos push components ./my-components
+```
+
+This command will:
+1. Connect to your Qelos instance using the configured credentials
+2. Read all `.vue` files from the specified directory
+3. For each file:
+   - Check if a component with the same identifier exists
+   - Update the existing component or create a new one
+   - Display progress for each component
+
+**Output:**
+```
+Pushing component: header-component
+Component updated: header-component
+Pushing component: new-component
+Component pushed: new-component
+All components pushed
+```
+
+### Workflow Example
+
+A typical workflow for working with components:
+
+```bash
+# Pull components from Qelos to work on them locally
+qelos pull components ./local-components
+
+# Make changes to the .vue files in ./local-components
+
+# Push the updated components back to Qelos
+qelos push components ./local-components
+```
+
+## Help
+
+View all available commands and options:
+
+```bash
+qelos --help
+qplay --help
+```
+
+View help for a specific command:
+
+```bash
+qelos pull --help
+qelos push --help
+```

package/commands/pull.mjs

@@ -2,12 +2,13 @@ import pullController from "../controllers/pull.mjs";
 
 export default function pullCommand(program) {
   program
-    .command('pull [type] [path]', 'pull from qelos app. Ability to pull components, plugins, integrations, blueprints, and more.',
+    .command('pull [type] [path]', 'pull from qelos app. Ability to pull components, blueprints, configurations, plugins, blocks, and more.',
       (yargs) => {
         return yargs
           .positional('type', {
-            describe: 'Type of the resource to pull. Can be components, plugins, integrations, blueprints, or more.',
+            describe: 'Type of the resource to pull. Can be components, blueprints, configurations, plugins, blocks, or all.',
             type: 'string',
+            choices: ['components', 'blueprints', 'configs', 'plugins', 'blocks', 'all', '*'],
             required: true
           })
           .positional('path', {

package/commands/push.mjs

@@ -2,16 +2,17 @@ import pushController from "../controllers/push.mjs";
 
 export default function createCommand(program) {
   program
-    .command('push [type] [path]', 'push to qelos app. Ability to push components, plugins, integrations, blueprints, and more.',
+    .command('push [type] [path]', 'push to qelos app. Ability to push components, blueprints, configurations, plugins, blocks, and more.',
       (yargs) => {
         return yargs
           .positional('type', {
-            describe: 'Type of the plugin to push. Can be components, plugins, integrations, blueprints, or more.',
+            describe: 'Type of the resource to push. Can be components, blueprints, configurations, plugins, blocks, or all.',
             type: 'string',
+            choices: ['components', 'blueprints', 'configs', 'plugins', 'blocks', 'all', '*'],
             required: true
           })
           .positional('path', {
-            describe: 'Path to the context file to push.',
+            describe: 'Path to the resource to push.',
             type: 'string',
             required: true
           })

package/controllers/pull.mjs

@@ -1,43 +1,81 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import {createJiti} from 'jiti';
-
-const jiti = createJiti(import.meta.url);
+import { initializeSdk } from '../services/sdk.mjs';
+import { pullComponents } from '../services/components.mjs';
+import { pullBlueprints } from '../services/blueprints.mjs';
+import { pullConfigurations } from '../services/configurations.mjs';
+import { pullPlugins } from '../services/plugins.mjs';
+import { pullBlocks } from '../services/blocks.mjs';
+import { logger } from '../services/logger.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
 
 export default async function pullController({ type, path: targetPath }) {
+  try {
+    // Validate parent directory exists
+    const parentDir = path.dirname(targetPath);
+    if (!fs.existsSync(parentDir)) {
+      logger.error(`Parent directory does not exist: ${parentDir}`);
+      logger.info('Please ensure the parent directory exists');
+      process.exit(1);
+    }
 
-  const QelosAdministratorSDK = await jiti('@qelos/sdk/src/administrator/index.ts');
+    // Warn if target path exists and is not a directory
+    if (fs.existsSync(targetPath) && !fs.statSync(targetPath).isDirectory()) {
+      logger.error(`Path exists but is not a directory: ${targetPath}`);
+      logger.info('Please provide a directory path, not a file');
+      process.exit(1);
+    }
 
-  const sdk = new QelosAdministratorSDK.default({
-    appUrl: process.env.QELOS_URL || "http://localhost:3000",
-  })
+    const sdk = await initializeSdk();
 
-  await sdk.authentication.oAuthSignin({
-    username: process.env.QELOS_USERNAME || 'test@test.com',
-    password: process.env.QELOS_PASSWORD || 'admin',
-  })
+    // Handle "all" or "*" type
+    if (type === 'all' || type === '*') {
+      logger.section(`Pulling all resources to ${targetPath}`);
+      
+      const types = [
+        { name: 'components', fn: pullComponents },
+        { name: 'blueprints', fn: pullBlueprints },
+        { name: 'configs', fn: pullConfigurations },
+        { name: 'plugins', fn: pullPlugins },
+        { name: 'blocks', fn: pullBlocks }
+      ];
 
-  // if type === 'components' - fetch all components and save them as vue files
-  if (type === 'components') {
-    // Create directory if it doesn't exist
-    if (!fs.existsSync(targetPath)) {
-      fs.mkdirSync(targetPath, { recursive: true })
-      console.log('Created directory:', targetPath)
+      for (const { name, fn } of types) {
+        const typePath = path.join(targetPath, name);
+        logger.section(`Pulling ${name} to ${typePath}`);
+        try {
+          await fn(sdk, typePath);
+          logger.success(`Successfully pulled ${name}`);
+        } catch (error) {
+          logger.error(`Failed to pull ${name}`, error);
+        }
+      }
+
+      logger.success(`Successfully pulled all resources to ${targetPath}`);
+      return;
     }
 
-    const components = await sdk.components.getList()
-    console.log(`Found ${components.length} components to pull`)
+    logger.section(`Pulling ${type} to ${targetPath}`);
 
-    await Promise.all(components.map(async (component) => {
-      const fileName = `${component.identifier}.vue`
-      const filePath = path.join(targetPath, fileName)
+    if (type === 'components') {
+      await pullComponents(sdk, targetPath);
+    } else if (type === 'blueprints') {
+      await pullBlueprints(sdk, targetPath);
+    } else if (type === 'plugins') {
+      await pullPlugins(sdk, targetPath);
+    } else if (type === 'blocks') {
+      await pullBlocks(sdk, targetPath);
+    } else if (type === 'config' || type === 'configs' || type === 'configuration') {
+      await pullConfigurations(sdk, targetPath);
+    } else {
+      logger.error(`Unknown type: ${type}`);
+      logger.info('Supported types: components, blueprints, plugins, blocks, config, configs, configuration, all');
+      process.exit(1);
+    }
 
-      const {content} = await sdk.components.getComponent(component._id);
-      
-      fs.writeFileSync(filePath, content, 'utf-8')
-      console.log('Pulled component:', component.identifier)
-    }))
+    logger.success(`Successfully pulled ${type} to ${targetPath}`);
 
-    console.log(`All ${components.length} components pulled to ${targetPath}`)
+  } catch (error) {
+    logger.error(`Failed to pull ${type}`, error);
+    process.exit(1);
   }
 }

package/controllers/push.mjs

@@ -1,47 +1,98 @@
-import fs from 'node:fs'
-import {createJiti} from 'jiti';
-
-const jiti = createJiti(import.meta.url);
-
-export default async function pushController({ type, path }) {
-
-  const QelosAdministratorSDK = await jiti('@qelos/sdk/src/administrator/index.ts');
-
-  const sdk = new QelosAdministratorSDK.default({
-    appUrl: process.env.QELOS_URL || "http://localhost:3000",
-  })
-
-  await sdk.authentication.oAuthSignin({
-    username: process.env.QELOS_USERNAME || 'test@test.com',
-    password: process.env.QELOS_PASSWORD || 'admin',
-  })
-
-  // if type === 'components' - load all vue files from path and push them using sdk
-  if (type === 'components') {
-    const files = fs.readdirSync(path)
-    const existingComponents = await sdk.components.getList()
-    await Promise.all(files.map(async (file) => {
-      if (file.endsWith('.vue')) {
-        const content = fs.readFileSync(path + '/' + file, 'utf-8')
-        console.log('Pushing component:', file.replace('.vue', ''))
-        const existingComponent = existingComponents.find(component => component.identifier === file.replace('.vue', ''))
-        if (existingComponent) {
-          await sdk.components.update(existingComponent._id, {
-            content,
-            description: 'Component description'
-          })
-          console.log('Component updated:', file.replace('.vue', ''))
-        } else {
-          await sdk.components.create({
-            identifier: file.replace('.vue', ''),
-            componentName: file.replace('.vue', ''),
-            content,
-            description: 'Component description'
-          })
-          console.log('Component pushed:', file.replace('.vue', ''))
+import { initializeSdk } from '../services/sdk.mjs';
+import { pushComponents } from '../services/components.mjs';
+import { pushBlueprints } from '../services/blueprints.mjs';
+import { pushConfigurations } from '../services/configurations.mjs';
+import { pushPlugins } from '../services/plugins.mjs';
+import { pushBlocks } from '../services/blocks.mjs';
+import { logger } from '../services/logger.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export default async function pushController({ type, path: sourcePath }) {
+  try {
+    // Validate path exists
+    if (!fs.existsSync(sourcePath)) {
+      logger.error(`Path does not exist: ${sourcePath}`);
+      logger.info('Please provide a valid directory path');
+      process.exit(1);
+    }
+
+    // Validate path is a directory
+    if (!fs.statSync(sourcePath).isDirectory()) {
+      logger.error(`Path is not a directory: ${sourcePath}`);
+      logger.info('Please provide a directory path, not a file');
+      process.exit(1);
+    }
+
+    const sdk = await initializeSdk();
+
+    // Handle "all" or "*" type
+    if (type === 'all' || type === '*') {
+      logger.section(`Pushing all resources from ${sourcePath}`);
+      
+      const types = [
+        { name: 'components', fn: pushComponents },
+        { name: 'blueprints', fn: pushBlueprints },
+        { name: 'configs', fn: pushConfigurations },
+        { name: 'plugins', fn: pushPlugins },
+        { name: 'blocks', fn: pushBlocks }
+      ];
+
+      for (const { name, fn } of types) {
+        const typePath = path.join(sourcePath, name);
+        
+        // Skip if directory doesn't exist
+        if (!fs.existsSync(typePath)) {
+          logger.info(`Skipping ${name} (directory not found: ${typePath})`);
+          continue;
+        }
+        
+        logger.section(`Pushing ${name} from ${typePath}`);
+        try {
+          await fn(sdk, typePath);
+          logger.success(`Successfully pushed ${name}`);
+        } catch (error) {
+          logger.error(`Failed to push ${name}`, error);
         }
       }
-    }))
-    console.log('All components pushed')
+
+      logger.success(`Successfully pushed all resources from ${sourcePath}`);
+      return;
+    }
+
+    logger.section(`Pushing ${type} from ${sourcePath}`);
+
+    if (type === 'components') {
+      await pushComponents(sdk, sourcePath);
+    } else if (type === 'blueprints') {
+      await pushBlueprints(sdk, sourcePath);
+    } else if (type === 'plugins') {
+      await pushPlugins(sdk, sourcePath);
+    } else if (type === 'blocks') {
+      await pushBlocks(sdk, sourcePath);
+    }  else if (type === 'config' || type === 'configs' || type === 'configuration') {
+      await pushConfigurations(sdk, sourcePath);
+    } else {
+      logger.error(`Unknown type: ${type}`);
+      logger.info('Supported types: components, blueprints, plugins, blocks, config, configs, configuration, all');
+      process.exit(1);
+    }
+
+    logger.success(`Successfully pushed ${type}`);
+
+  } catch (error) {
+    // Don't log the error again if it's already been logged by the service
+    if (!error.message?.includes('Failed to push')) {
+      logger.error(`Failed to push ${type}`, error);
+    }
+    
+    if (process.env.VERBOSE) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    } else {
+      console.error('\nRun with VERBOSE=true for full stack trace');
+    }
+    
+    process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/plugins-cli",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "CLI to manage QELOS plugins",
   "main": "cli.mjs",
   "bin": {

package/services/blocks.mjs

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { logger } from './logger.mjs';
+
+/**
+ * Convert string to kebab-case
+ */
+function toKebabCase(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+/**
+ * Push blocks from local directory to remote
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} path - Path to blocks directory
+ */
+export async function pushBlocks(sdk, path) {
+  const files = fs.readdirSync(path);
+  const blockFiles = files.filter(f => f.endsWith('.html'));
+  
+  if (blockFiles.length === 0) {
+    logger.warning(`No .html files found in ${path}`);
+    return;
+  }
+  
+  logger.info(`Found ${blockFiles.length} block(s) to push`);
+  let blocksJson = {};
+  
+  try {
+    const jsonPath = join(path, 'blocks.json');
+    if (fs.existsSync(jsonPath)) {
+      blocksJson = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+    }
+  } catch (error) {
+    logger.debug('No blocks.json found or invalid format');
+  }
+  
+  const existingBlocks = await sdk.blocks.getList();
+  const updatedBlocksJson = { ...blocksJson };
+  
+  await Promise.all(blockFiles.map(async (file) => {
+    const fileName = file.replace('.html', '');
+    const info = blocksJson[fileName] || {};
+    const content = fs.readFileSync(join(path, file), 'utf-8');
+    
+    logger.step(`Pushing block: ${fileName}`);
+    
+    // First check if we have an _id in blocks.json
+    let blockId = info._id;
+    
+    // If we have an _id, try to update directly
+    if (blockId) {
+      try {
+        await sdk.blocks.update(blockId, {
+          name: info.name || fileName,
+          content,
+          contentType: info.contentType || 'html',
+          description: info.description || 'Block description'
+        });
+        logger.success(`Updated: ${fileName}`);
+        return;
+      } catch (error) {
+        // If update fails, the block might have been deleted, so we'll create a new one
+        logger.debug(`Block ${fileName} not found by _id, will search or create`);
+      }
+    }
+    
+    // Try to find existing block by name
+    const existingBlock = existingBlocks.find(
+      block => toKebabCase(block.name) === fileName
+    );
+    
+    if (existingBlock) {
+      await sdk.blocks.update(existingBlock._id, {
+        name: info.name || existingBlock.name,
+        content,
+        contentType: info.contentType || 'html',
+        description: info.description || existingBlock.description || 'Block description'
+      });
+      updatedBlocksJson[fileName] = {
+        ...info,
+        _id: existingBlock._id
+      };
+      logger.success(`Updated: ${fileName}`);
+    } else {
+      const newBlock = await sdk.blocks.create({
+        name: info.name || fileName,
+        content,
+        contentType: info.contentType || 'html',
+        description: info.description || 'Block description'
+      });
+      updatedBlocksJson[fileName] = {
+        ...info,
+        _id: newBlock._id,
+        name: newBlock.name
+      };
+      logger.success(`Created: ${fileName}`);
+    }
+  }));
+  
+  // Update blocks.json with new _ids
+  fs.writeFileSync(
+    join(path, 'blocks.json'),
+    JSON.stringify(updatedBlocksJson, null, 2)
+  );
+  
+  logger.info(`Pushed ${blockFiles.length} block(s)`);
+}
+
+/**
+ * Pull blocks from remote to local directory
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} targetPath - Path to save blocks
+ */
+export async function pullBlocks(sdk, targetPath) {
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    logger.info(`Created directory: ${targetPath}`);
+  }
+
+  const blocks = await sdk.blocks.getList();
+  
+  if (blocks.length === 0) {
+    logger.warning('No blocks found to pull');
+    return;
+  }
+  
+  logger.info(`Found ${blocks.length} block(s) to pull`);
+
+  const blocksInformation = await Promise.all(blocks.map(async (block) => {
+    const fileName = toKebabCase(block.name);
+    const filePath = join(targetPath, `${fileName}.html`);
+
+    const blockDetails = await sdk.blocks.getBlock(block._id);
+    
+    fs.writeFileSync(filePath, blockDetails.content, 'utf-8');
+    logger.step(`Pulled: ${block.name}`);
+
+    return {
+      _id: block._id,
+      name: block.name,
+      description: blockDetails.description,
+      contentType: blockDetails.contentType,
+    };
+  }));
+
+  fs.writeFileSync(
+    join(targetPath, 'blocks.json'),
+    JSON.stringify(
+      blocksInformation.reduce((obj, current) => {
+        const fileName = toKebabCase(current.name);
+        obj[fileName] = current;
+        return obj;
+      }, {}),
+      null,
+      2
+    )
+  );
+
+  logger.info(`Saved blocks.json with metadata`);
+  logger.info(`Pulled ${blocks.length} block(s)`);
+}

package/services/blueprints.mjs

@@ -0,0 +1,157 @@
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { logger } from './logger.mjs';
+
+/**
+ * Push blueprints from local directory to remote
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} path - Path to blueprints directory
+ */
+export async function pushBlueprints(sdk, path) {
+  const files = fs.readdirSync(path);
+  const blueprintFiles = files.filter(f => f.endsWith('.blueprint.json'));
+  
+  if (blueprintFiles.length === 0) {
+    logger.warning(`No blueprint files (*.blueprint.json) found in ${path}`);
+    return;
+  }
+  
+  logger.info(`Found ${blueprintFiles.length} blueprint(s) to push`);
+  const existingBlueprints = await sdk.manageBlueprints.getList();
+  
+  const results = await Promise.allSettled(blueprintFiles.map(async (file) => {
+    if (file.endsWith('.blueprint.json')) {
+      let blueprintData;
+      try {
+        blueprintData = JSON.parse(fs.readFileSync(join(path, file), 'utf-8'));
+      } catch (error) {
+        logger.error(`Failed to parse ${file}`, error);
+        throw new Error(`Parse error in ${file}: ${error.message}`);
+      }
+      
+      const identifier = blueprintData.identifier;
+      
+      if (!identifier) {
+        logger.warning(`Skipping ${file}: missing identifier field`);
+        return { skipped: true, file };
+      }
+      
+      logger.step(`Pushing blueprint: ${identifier}`);
+      
+      const existingBlueprint = existingBlueprints.find(
+        blueprint => blueprint.identifier === identifier
+      );
+      
+      try {
+        if (existingBlueprint) {
+          await sdk.manageBlueprints.update(identifier, blueprintData);
+          logger.success(`Updated: ${identifier}`);
+        } else {
+          await sdk.manageBlueprints.create(blueprintData);
+          logger.success(`Created: ${identifier}`);
+        }
+        return { success: true, identifier };
+      } catch (error) {
+        // Extract detailed error information
+        let errorMessage = error.message || 'Unknown error';
+        let errorDetails = null;
+        
+        // The SDK throws the response body as the error
+        if (typeof error === 'object' && error !== null) {
+          if (error.message) {
+            errorMessage = error.message;
+          }
+          if (error.error) {
+            errorDetails = error.error;
+          }
+          if (error.errors) {
+            errorDetails = error.errors;
+          }
+        }
+        
+        logger.error(`Failed to push ${identifier}: ${errorMessage}`);
+        
+        if (errorDetails) {
+          if (typeof errorDetails === 'string') {
+            logger.error(`  Details: ${errorDetails}`);
+          } else {
+            logger.error(`  Details: ${JSON.stringify(errorDetails, null, 2)}`);
+          }
+        }
+        
+        if (process.env.VERBOSE && error.stack) {
+          logger.debug(`Stack: ${error.stack}`);
+        }
+        
+        throw new Error(`Failed to push ${identifier}: ${errorMessage}`);
+      }
+    }
+  }));
+  
+  // Check for failures
+  const failures = results.filter(r => r.status === 'rejected');
+  const successes = results.filter(r => r.status === 'fulfilled' && r.value?.success);
+  
+  if (failures.length > 0) {
+    logger.error(`\n${failures.length} blueprint(s) failed to push:`);
+    failures.forEach(f => {
+      logger.error(`  • ${f.reason.message}`);
+    });
+    throw new Error(`Failed to push ${failures.length} blueprint(s)`);
+  }
+  
+  logger.info(`Pushed ${blueprintFiles.length} blueprint(s)`);
+}
+
+/**
+ * Pull blueprints from remote to local directory
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} targetPath - Path to save blueprints
+ */
+export async function pullBlueprints(sdk, targetPath) {
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    logger.info(`Created directory: ${targetPath}`);
+  }
+
+  const blueprints = await sdk.manageBlueprints.getList();
+  
+  if (blueprints.length === 0) {
+    logger.warning('No blueprints found to pull');
+    return;
+  }
+  
+  logger.info(`Found ${blueprints.length} blueprint(s) to pull`);
+
+  await Promise.all(blueprints.map(async (blueprint) => {
+    const fileName = `${blueprint.identifier}.blueprint.json`;
+    const filePath = join(targetPath, fileName);
+
+    // Fetch full blueprint details
+    const fullBlueprint = await sdk.manageBlueprints.getBlueprint(blueprint.identifier);
+
+    function removeIdFromObject(obj) {
+      const { _id, ...rest } = obj;
+      return rest;
+    }
+
+    const relevantFields = {
+      identifier: fullBlueprint.identifier,
+      name: fullBlueprint.name,
+      description: fullBlueprint.description,
+      properties: fullBlueprint.properties,
+      relations: fullBlueprint.relations,
+      dispatchers: fullBlueprint.dispatchers,
+      permissions: (fullBlueprint.permissions || []).map(removeIdFromObject),
+      permissionScope: fullBlueprint.permissionScope,
+      entityIdentifierMechanism: fullBlueprint.entityIdentifierMechanism,
+      limitations: (fullBlueprint.limitations || []).map(removeIdFromObject),
+    }
+    
+    fs.writeFileSync(filePath, JSON.stringify(relevantFields, null, 2), 'utf-8');
+    logger.step(`Pulled: ${blueprint.identifier}`);
+  }));
+
+  logger.info(`Pulled ${blueprints.length} blueprint(s)`);
+}

package/services/components.mjs

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { logger } from './logger.mjs';
+
+/**
+ * Push components from local directory to remote
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} path - Path to components directory
+ */
+export async function pushComponents(sdk, path) {
+  const files = fs.readdirSync(path);
+  const vueFiles = files.filter(f => f.endsWith('.vue'));
+  
+  if (vueFiles.length === 0) {
+    logger.warning(`No .vue files found in ${path}`);
+    return;
+  }
+  
+  logger.info(`Found ${vueFiles.length} component(s) to push`);
+  let componentsJson = {};
+  
+  try {
+    const jsonPath = join(path, 'components.json');
+    if (fs.existsSync(jsonPath)) {
+      componentsJson = JSON.parse(fs.readFileSync(jsonPath));
+    }
+  } catch (error) {
+    logger.debug('No components.json found or invalid format');
+  }
+  
+  const existingComponents = await sdk.components.getList();
+  
+  await Promise.all(files.map(async (file) => {
+    if (file.endsWith('.vue')) {
+      const componentName = file.replace('.vue', '');
+      const info = componentsJson[componentName] || {};
+      const content = fs.readFileSync(join(path, file), 'utf-8');
+      
+      logger.step(`Pushing component: ${componentName}`);
+      
+      const existingComponent = existingComponents.find(
+        component => component.identifier === componentName
+      );
+      
+      if (existingComponent) {
+        await sdk.components.update(existingComponent._id, {
+          identifier: info.identifier || existingComponent.identifier || componentName,
+          componentName: componentName,
+          content,
+          description: info.description || existingComponent.description || 'Component description'
+        });
+        logger.success(`Updated: ${componentName}`);
+      } else {
+        await sdk.components.create({
+          identifier: info.identifier || componentName,
+          componentName: componentName,
+          content,
+          description: info.description || 'Component description'
+        });
+        logger.success(`Created: ${componentName}`);
+      }
+    }
+  }));
+  
+  logger.info(`Pushed ${vueFiles.length} component(s)`);
+}
+
+/**
+ * Pull components from remote to local directory
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} targetPath - Path to save components
+ */
+export async function pullComponents(sdk, targetPath) {
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    logger.info(`Created directory: ${targetPath}`);
+  }
+
+  const components = await sdk.components.getList();
+  
+  if (components.length === 0) {
+    logger.warning('No components found to pull');
+    return;
+  }
+  
+  logger.info(`Found ${components.length} component(s) to pull`);
+
+  const componentsInformation = await Promise.all(components.map(async (component) => {
+    const fileName = `${component.componentName}.vue`;
+    const filePath = join(targetPath, fileName);
+
+    const { content, description } = await sdk.components.getComponent(component._id);
+    
+    fs.writeFileSync(filePath, content, 'utf-8');
+    logger.step(`Pulled: ${component.identifier}`);
+
+    return {
+      _id: component._id,
+      componentName: component.componentName,
+      identifier: component.identifier,
+      description,
+    };
+  }));
+
+  fs.writeFileSync(
+    join(targetPath, 'components.json'),
+    JSON.stringify(
+      componentsInformation.reduce((obj, current) => {
+        obj[current.componentName] = current;
+        return obj;
+      }, {}),
+      null,
+      2
+    )
+  );
+
+  logger.info(`Saved components.json with metadata`);
+  logger.info(`Pulled ${components.length} component(s)`);
+}

package/services/configurations.mjs

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { logger } from './logger.mjs';
+
+/**
+ * Push configurations from local directory to remote
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} path - Path to configurations directory
+ */
+export async function pushConfigurations(sdk, path) {
+  const files = fs.readdirSync(path);
+  const configFiles = files.filter(f => f.endsWith('.config.json'));
+  
+  if (configFiles.length === 0) {
+    logger.warning(`No configuration files (*.config.json) found in ${path}`);
+    return;
+  }
+  
+  logger.info(`Found ${configFiles.length} configuration(s) to push`);
+  const existingConfigurations = await sdk.manageConfigurations.getList();
+  
+  const results = await Promise.allSettled(configFiles.map(async (file) => {
+    if (file.endsWith('.config.json')) {
+      let configData;
+      try {
+        configData = JSON.parse(fs.readFileSync(join(path, file), 'utf-8'));
+      } catch (error) {
+        logger.error(`Failed to parse ${file}`, error);
+        throw new Error(`Parse error in ${file}: ${error.message}`);
+      }
+      
+      const key = configData.key;
+      
+      if (!key) {
+        logger.warning(`Skipping ${file}: missing key field`);
+        return { skipped: true, file };
+      }
+      
+      logger.step(`Pushing configuration: ${key}`);
+      
+      const existingConfig = existingConfigurations.find(
+        config => config.key === key
+      );
+      
+      try {
+        if (existingConfig) {
+          await sdk.manageConfigurations.update(key, configData);
+          logger.success(`Updated: ${key}`);
+        } else {
+          await sdk.manageConfigurations.create(configData);
+          logger.success(`Created: ${key}`);
+        }
+        return { success: true, key };
+      } catch (error) {
+        // Extract detailed error information
+        let errorMessage = error.message || 'Unknown error';
+        let errorDetails = null;
+        
+        // The SDK throws the response body as the error
+        if (typeof error === 'object' && error !== null) {
+          if (error.message) {
+            errorMessage = error.message;
+          }
+          if (error.error) {
+            errorDetails = error.error;
+          }
+          if (error.errors) {
+            errorDetails = error.errors;
+          }
+        }
+        
+        logger.error(`Failed to push ${key}: ${errorMessage}`);
+        
+        if (errorDetails) {
+          if (typeof errorDetails === 'string') {
+            logger.error(`  Details: ${errorDetails}`);
+          } else {
+            logger.error(`  Details: ${JSON.stringify(errorDetails, null, 2)}`);
+          }
+        }
+        
+        if (process.env.VERBOSE && error.stack) {
+          logger.debug(`Stack: ${error.stack}`);
+        }
+        
+        throw new Error(`Failed to push ${key}: ${errorMessage}`);
+      }
+    }
+  }));
+  
+  // Check for failures
+  const failures = results.filter(r => r.status === 'rejected');
+  const successes = results.filter(r => r.status === 'fulfilled' && r.value?.success);
+  
+  if (failures.length > 0) {
+    logger.error(`\n${failures.length} configuration(s) failed to push:`);
+    failures.forEach(f => {
+      logger.error(`  • ${f.reason.message}`);
+    });
+    throw new Error(`Failed to push ${failures.length} configuration(s)`);
+  }
+  
+  logger.info(`Pushed ${configFiles.length} configuration(s)`);
+}
+
+/**
+ * Pull configurations from remote to local directory
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} targetPath - Path to save configurations
+ */
+export async function pullConfigurations(sdk, targetPath) {
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    logger.info(`Created directory: ${targetPath}`);
+  }
+
+  const configurations = await sdk.manageConfigurations.getList();
+  
+  if (configurations.length === 0) {
+    logger.warning('No configurations found to pull');
+    return;
+  }
+  
+  logger.info(`Found ${configurations.length} configuration(s) to pull`);
+
+  await Promise.all(configurations.map(async (config) => {
+    const fileName = `${config.key}.config.json`;
+    const filePath = join(targetPath, fileName);
+
+    // Fetch full configuration details
+    const fullConfig = await sdk.manageConfigurations.getConfiguration(config.key);
+    
+    // Remove fields that shouldn't be in the file
+    const { _id, tenant, created, updated, ...relevantFields } = fullConfig;
+    
+    fs.writeFileSync(filePath, JSON.stringify(relevantFields, null, 2), 'utf-8');
+    logger.step(`Pulled: ${config.key}`);
+  }));
+
+  logger.info(`Pulled ${configurations.length} configuration(s)`);
+}

package/services/logger.mjs

@@ -0,0 +1,112 @@
+/**
+ * Logger utility for CLI with colored output and consistent formatting
+ */
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+};
+
+export const logger = {
+  success(message) {
+    console.log(`${colors.green}✓${colors.reset} ${message}`);
+  },
+
+  error(message, error = null) {
+    console.error(`${colors.red}✗ Error:${colors.reset} ${message}`);
+    if (error && process.env.VERBOSE) {
+      console.error(`${colors.gray}${error.stack || error}${colors.reset}`);
+    }
+  },
+
+  warning(message) {
+    console.warn(`${colors.yellow}⚠ Warning:${colors.reset} ${message}`);
+  },
+
+  info(message) {
+    console.log(`${colors.blue}ℹ${colors.reset} ${message}`);
+  },
+
+  debug(message) {
+    if (process.env.VERBOSE) {
+      console.log(`${colors.gray}[DEBUG]${colors.reset} ${message}`);
+    }
+  },
+
+  step(message) {
+    console.log(`${colors.cyan}→${colors.reset} ${message}`);
+  },
+
+  section(title) {
+    console.log(`\n${colors.bright}${title}${colors.reset}`);
+  },
+
+  /**
+   * Format and display a connection error with helpful context
+   */
+  connectionError(url, error) {
+    console.error(`\n${colors.red}✗ Connection Failed${colors.reset}`);
+    console.error(`${colors.dim}Unable to connect to: ${colors.reset}${url}`);
+    
+    if (error.code === 'UND_ERR_CONNECT_TIMEOUT') {
+      console.error(`${colors.yellow}Reason:${colors.reset} Connection timeout (10s)`);
+      console.error(`\n${colors.cyan}Suggestions:${colors.reset}`);
+      console.error(`  • Check if the server is running and accessible`);
+      console.error(`  • Verify the QELOS_URL is correct: ${url}`);
+      console.error(`  • Check your network connection`);
+      console.error(`  • Ensure there are no firewall rules blocking the connection`);
+    } else if (error.code === 'ENOTFOUND') {
+      console.error(`${colors.yellow}Reason:${colors.reset} Domain not found`);
+      console.error(`\n${colors.cyan}Suggestions:${colors.reset}`);
+      console.error(`  • Verify the QELOS_URL is correct: ${url}`);
+      console.error(`  • Check if the domain exists and is accessible`);
+    } else if (error.code === 'ECONNREFUSED') {
+      console.error(`${colors.yellow}Reason:${colors.reset} Connection refused`);
+      console.error(`\n${colors.cyan}Suggestions:${colors.reset}`);
+      console.error(`  • Check if the server is running on ${url}`);
+      console.error(`  • Verify the port number is correct`);
+    } else {
+      console.error(`${colors.yellow}Reason:${colors.reset} ${error.message}`);
+    }
+
+    if (process.env.VERBOSE) {
+      console.error(`\n${colors.gray}Full error:${colors.reset}`);
+      console.error(`${colors.gray}${error.stack}${colors.reset}`);
+    } else {
+      console.error(`\n${colors.dim}Run with VERBOSE=true for more details${colors.reset}`);
+    }
+  },
+
+  /**
+   * Format and display an authentication error
+   */
+  authError(username, url) {
+    console.error(`\n${colors.red}✗ Authentication Failed${colors.reset}`);
+    console.error(`${colors.dim}Unable to authenticate user: ${colors.reset}${username}`);
+    console.error(`${colors.dim}Server: ${colors.reset}${url}`);
+    console.error(`\n${colors.cyan}Suggestions:${colors.reset}`);
+    console.error(`  • Verify QELOS_USERNAME is correct: ${username}`);
+    console.error(`  • Check if QELOS_PASSWORD is correct`);
+    console.error(`  • Ensure the user account exists and is active`);
+    console.error(`  • Verify you have the necessary permissions`);
+  },
+
+  /**
+   * Display environment configuration
+   */
+  showConfig(config) {
+    console.log(`\n${colors.bright}Configuration:${colors.reset}`);
+    Object.entries(config).forEach(([key, value]) => {
+      const displayValue = key.toLowerCase().includes('password') ? '***' : value;
+      console.log(`  ${colors.cyan}${key}:${colors.reset} ${displayValue}`);
+    });
+    console.log('');
+  }
+};

package/services/plugins.mjs

@@ -0,0 +1,159 @@
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { logger } from './logger.mjs';
+
+/**
+ * Push plugins from local directory to remote
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} path - Path to plugins directory
+ */
+export async function pushPlugins(sdk, path) {
+  const files = fs.readdirSync(path);
+  const pluginFiles = files.filter(f => f.endsWith('.plugin.json'));
+  
+  if (pluginFiles.length === 0) {
+    logger.warning(`No plugin files (*.plugin.json) found in ${path}`);
+    return;
+  }
+  
+  logger.info(`Found ${pluginFiles.length} plugin(s) to push`);
+  const existingPlugins = await sdk.managePlugins.getList();
+  
+  const results = await Promise.allSettled(pluginFiles.map(async (file) => {
+    if (file.endsWith('.plugin.json')) {
+      let pluginData;
+      try {
+        pluginData = JSON.parse(fs.readFileSync(join(path, file), 'utf-8'));
+      } catch (error) {
+        logger.error(`Failed to parse ${file}`, error);
+        throw new Error(`Parse error in ${file}: ${error.message}`);
+      }
+      
+      const apiPath = pluginData.apiPath;
+      
+      if (!apiPath) {
+        logger.warning(`Skipping ${file}: missing apiPath field`);
+        return { skipped: true, file };
+      }
+      
+      logger.step(`Pushing plugin: ${apiPath}`);
+      
+      const existingPlugin = existingPlugins.find(
+        plugin => plugin.apiPath === apiPath
+      );
+      
+      try {
+        if (existingPlugin) {
+          await sdk.managePlugins.update(existingPlugin._id, pluginData);
+          logger.success(`Updated: ${apiPath}`);
+        } else {
+          await sdk.managePlugins.create(pluginData);
+          logger.success(`Created: ${apiPath}`);
+        }
+        return { success: true, apiPath };
+      } catch (error) {
+        // Extract detailed error information
+        let errorMessage = error.message || 'Unknown error';
+        let errorDetails = null;
+        
+        // The SDK throws the response body as the error
+        if (typeof error === 'object' && error !== null) {
+          if (error.message) {
+            errorMessage = error.message;
+          }
+          if (error.error) {
+            errorDetails = error.error;
+          }
+          if (error.errors) {
+            errorDetails = error.errors;
+          }
+        }
+        
+        logger.error(`Failed to push ${apiPath}: ${errorMessage}`);
+        
+        if (errorDetails) {
+          if (typeof errorDetails === 'string') {
+            logger.error(`  Details: ${errorDetails}`);
+          } else {
+            logger.error(`  Details: ${JSON.stringify(errorDetails, null, 2)}`);
+          }
+        }
+        
+        if (process.env.VERBOSE && error.stack) {
+          logger.debug(`Stack: ${error.stack}`);
+        }
+        
+        throw new Error(`Failed to push ${apiPath}: ${errorMessage}`);
+      }
+    }
+  }));
+  
+  // Check for failures
+  const failures = results.filter(r => r.status === 'rejected');
+  
+  if (failures.length > 0) {
+    logger.error(`\n${failures.length} plugin(s) failed to push:`);
+    failures.forEach(f => {
+      logger.error(`  • ${f.reason.message}`);
+    });
+    throw new Error(`Failed to push ${failures.length} plugin(s)`);
+  }
+  
+  logger.info(`Pushed ${pluginFiles.length} plugin(s)`);
+}
+
+/**
+ * Pull plugins from remote to local directory
+ * @param {Object} sdk - Initialized SDK instance
+ * @param {string} targetPath - Path to save plugins
+ */
+export async function pullPlugins(sdk, targetPath) {
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    logger.info(`Created directory: ${targetPath}`);
+  }
+
+  const plugins = await sdk.managePlugins.getList();
+  
+  if (plugins.length === 0) {
+    logger.warning('No plugins found to pull');
+    return;
+  }
+  
+  logger.info(`Found ${plugins.length} plugin(s) to pull`);
+
+  await Promise.all(plugins.map(async (plugin) => {
+    const fileName = `${plugin.apiPath}.plugin.json`;
+    const filePath = join(targetPath, fileName);
+
+    // Fetch full plugin details
+    const fullPlugin = await sdk.managePlugins.getById(plugin._id);
+
+    function removeIdFromObject(obj) {
+      const { _id, ...rest } = obj;
+      return rest;
+    }
+
+    const relevantFields = {
+      name: fullPlugin.name,
+      description: fullPlugin.description,
+      manifestUrl: fullPlugin.manifestUrl,
+      callbackUrl: fullPlugin.callbackUrl,
+      registerUrl: fullPlugin.registerUrl,
+      apiPath: fullPlugin.apiPath,
+      authAcquire: fullPlugin.authAcquire,
+      proxyUrl: fullPlugin.proxyUrl,
+      subscribedEvents: (fullPlugin.subscribedEvents || []).map(removeIdFromObject),
+      microFrontends: (fullPlugin.microFrontends || []).map(removeIdFromObject),
+      injectables: (fullPlugin.injectables || []).map(removeIdFromObject),
+      navBarGroups: (fullPlugin.navBarGroups || []).map(removeIdFromObject),
+      cruds: (fullPlugin.cruds || []).map(removeIdFromObject),
+    }
+    
+    fs.writeFileSync(filePath, JSON.stringify(relevantFields, null, 2), 'utf-8');
+    logger.step(`Pulled: ${plugin.apiPath}`);
+  }));
+
+  logger.info(`Pulled ${plugins.length} plugin(s)`);
+}

package/services/sdk.mjs

@@ -0,0 +1,57 @@
+import { createJiti } from 'jiti';
+import { logger } from './logger.mjs';
+
+const jiti = createJiti(import.meta.url);
+
+export async function initializeSdk() {
+  const appUrl = process.env.QELOS_URL || "http://localhost:3000";
+  const username = process.env.QELOS_USERNAME || 'test@test.com';
+  const password = process.env.QELOS_PASSWORD || 'admin';
+
+  try {
+    logger.debug('Initializing Qelos SDK...');
+    
+    if (process.env.VERBOSE) {
+      logger.showConfig({
+        'QELOS_URL': appUrl,
+        'QELOS_USERNAME': username,
+        'QELOS_PASSWORD': password
+      });
+    }
+
+    const QelosAdministratorSDK = await jiti('@qelos/sdk/src/administrator/index.ts');
+
+    const sdk = new QelosAdministratorSDK.default({
+      appUrl,
+    });
+
+    logger.debug(`Authenticating as ${username}...`);
+
+    await sdk.authentication.oAuthSignin({
+      username,
+      password,
+    });
+
+    logger.debug('Authentication successful');
+    return sdk;
+
+  } catch (error) {
+    // Handle connection errors
+    if (error.cause?.code === 'UND_ERR_CONNECT_TIMEOUT' || 
+        error.cause?.code === 'ENOTFOUND' || 
+        error.cause?.code === 'ECONNREFUSED' ||
+        error.message?.includes('fetch failed')) {
+      logger.connectionError(appUrl, error.cause || error);
+    } 
+    // Handle authentication errors
+    else if (error.response?.status === 401 || error.message?.includes('authentication')) {
+      logger.authError(username, appUrl);
+    }
+    // Handle other errors
+    else {
+      logger.error('Failed to initialize SDK', error);
+    }
+
+    process.exit(1);
+  }
+}