@qelos/plugins-cli 0.0.8 → 0.0.10

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, 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, or more.',
             type: 'string',
+            choices: ['components', 'blueprints', 'configs'],
             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, 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, or more.',
             type: 'string',
+            choices: ['components', 'blueprints', 'configs'],
             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,37 +1,48 @@
-import QelosAdministratorSDK from "@qelos/sdk/src/administrator";
-import fs from 'node:fs'
-import path from 'node:path'
+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 { 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);
+    }
+
+    // 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({
-    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',
-  })
+    logger.section(`Pulling ${type} to ${targetPath}`);
 
-  // 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)
+    if (type === 'components') {
+      await pullComponents(sdk, targetPath);
+    } else if (type === 'blueprints') {
+      await pullBlueprints(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, config, configs, configuration');
+      process.exit(1);
     }
 
-    const components = await sdk.components.getList()
-    console.log(`Found ${components.length} components to pull`)
-
-    await Promise.all(components.map(async (component) => {
-      const fileName = `${component.identifier}.vue`
-      const filePath = path.join(targetPath, fileName)
-      
-      fs.writeFileSync(filePath, component.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,43 +1,57 @@
-import QelosAdministratorSDK from "@qelos/sdk/src/administrator";
-import fs from 'node:fs'
+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 { logger } from '../services/logger.mjs';
+import fs from 'node:fs';
 
-export default async  function pushController({ type, path }) {
+export default async function pushController({ type, path }) {
+  try {
+    // Validate path exists
+    if (!fs.existsSync(path)) {
+      logger.error(`Path does not exist: ${path}`);
+      logger.info('Please provide a valid directory path');
+      process.exit(1);
+    }
 
-  const sdk = new QelosAdministratorSDK({
-    appUrl: process.env.QELOS_URL || "http://localhost:3000",
-  })
+    // Validate path is a directory
+    if (!fs.statSync(path).isDirectory()) {
+      logger.error(`Path is not a directory: ${path}`);
+      logger.info('Please provide a directory path, not a file');
+      process.exit(1);
+    }
 
-  await sdk.authentication.oAuthSignin({
-    username: process.env.QELOS_USERNAME || 'test@test.com',
-    password: process.env.QELOS_PASSWORD || 'admin',
-  })
+    const sdk = await initializeSdk();
 
-  // 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', ''))
-        }
-      }
-    }))
-    console.log('All components pushed')
+    logger.section(`Pushing ${type} from ${path}`);
+
+    if (type === 'components') {
+      await pushComponents(sdk, path);
+    } else if (type === 'blueprints') {
+      await pushBlueprints(sdk, path);
+    } else if (type === 'config' || type === 'configs' || type === 'configuration') {
+      await pushConfigurations(sdk, path);
+    } else {
+      logger.error(`Unknown type: ${type}`);
+      logger.info('Supported types: components, blueprints, config, configs, configuration');
+      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.8",
+  "version": "0.0.10",
   "description": "CLI to manage QELOS plugins",
   "main": "cli.mjs",
   "bin": {
@@ -19,6 +19,7 @@
     "cli-select": "^1.1.2",
     "decompress-zip": "^0.3.3",
     "follow-redirects": "^1.15.11",
+    "jiti": "^2.6.1",
     "rimraf": "^6.0.1",
     "yargs": "^18.0.0",
     "zx": "^8.8.5"

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/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);
+  }
+}