@aifabrix/builder 2.32.3 → 2.33.0

package/lib/commands/wizard.js

@@ -1,29 +1,14 @@
 /**
- * @fileoverview Wizard command handler - interactive external system creation
+ * @fileoverview Wizard command handler - interactive and headless external system creation
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
 const chalk = require('chalk');
-const ora = require('ora');
-const path = require('path');
-const fs = require('fs').promises;
 const logger = require('../utils/logger');
-const config = require('../core/config');
-const { getDeviceOnlyAuth } = require('../utils/token-manager');
-const { getDataplaneUrl } = require('../datasource/deploy');
-const { resolveControllerUrl } = require('../utils/controller-url');
-const {
-  createWizardSession,
-  updateWizardSession,
-  parseOpenApi,
-  detectType,
-  generateConfig,
-  validateWizardConfig,
-  getDeploymentDocs
-} = require('../api/wizard.api');
 const {
   promptForMode,
+  promptForSystemIdOrKey,
   promptForSourceType,
   promptForOpenApiFile,
   promptForOpenApiUrl,
@@ -34,99 +19,90 @@ const {
   promptForConfigReview,
   promptForAppName
 } = require('../generator/wizard-prompts');
-const { generateWizardFiles } = require('../generator/wizard');
+const {
+  validateAndCheckAppDirectory,
+  handleOpenApiParsing,
+  handleCredentialSelection,
+  handleTypeDetection,
+  handleConfigurationGeneration,
+  validateWizardConfiguration,
+  handleFileSaving,
+  setupDataplaneAndAuth
+} = require('./wizard-core');
+const { handleWizardHeadless } = require('./wizard-headless');
+const { createWizardSession, updateWizardSession } = require('../api/wizard.api');
 
 /**
- * Validate app name and check if directory exists
- * @async
- * @function validateAndCheckAppDirectory
- * @param {string} appName - Application name
- * @returns {Promise<boolean>} True if should continue, false if cancelled
- * @throws {Error} If validation fails
+ * Extract session ID from response data
+ * @function extractSessionId
+ * @param {Object} responseData - Response data from API
+ * @returns {string} Session ID
+ * @throws {Error} If session ID not found or invalid
  */
-async function validateAndCheckAppDirectory(appName) {
-  if (!/^[a-z0-9-_]+$/.test(appName)) {
-    throw new Error('Application name must contain only lowercase letters, numbers, hyphens, and underscores');
+function extractSessionId(responseData) {
+  let sessionId = responseData?.data?.sessionId || responseData?.sessionId ||
+                  responseData?.data?.session_id || responseData?.session_id;
+  if (sessionId && typeof sessionId === 'object') {
+    sessionId = sessionId.id || sessionId.sessionId || sessionId.session_id;
   }
-  const appPath = path.join(process.cwd(), 'integration', appName);
-  try {
-    await fs.access(appPath);
-    const { overwrite } = await require('inquirer').prompt([{
-      type: 'confirm',
-      name: 'overwrite',
-      message: `Directory ${appPath} already exists. Overwrite?`,
-      default: false
-    }]);
-    if (!overwrite) {
-      logger.log(chalk.yellow('Wizard cancelled.'));
-      return false;
-    }
-  } catch (error) {
-    if (error.code !== 'ENOENT') {
-      throw error;
-    }
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new Error(`Session ID not found: ${JSON.stringify(responseData, null, 2)}`);
   }
-  return true;
+  return sessionId;
 }
 
 /**
- * Handle mode selection step - create wizard session
+ * Handle interactive mode selection step
  * @async
- * @function handleModeSelection
+ * @function handleInteractiveModeSelection
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
  * @returns {Promise<Object>} Object with mode and sessionId
- * @throws {Error} If mode selection fails
  */
-async function handleModeSelection(dataplaneUrl, authConfig) {
-  logger.log(chalk.blue('\n📋 Step 1: Mode Selection'));
+async function handleInteractiveModeSelection(dataplaneUrl, authConfig) {
+  logger.log(chalk.blue('\n\uD83D\uDCCB Step 1: Mode Selection'));
   const mode = await promptForMode();
-  const sessionResponse = await createWizardSession(dataplaneUrl, authConfig, mode);
+  let systemIdOrKey = null;
+  if (mode === 'add-datasource') {
+    systemIdOrKey = await promptForSystemIdOrKey();
+  }
+  const sessionResponse = await createWizardSession(dataplaneUrl, authConfig, mode, systemIdOrKey);
   if (!sessionResponse.success || !sessionResponse.data) {
-    const errorMsg = sessionResponse.formattedError ||
-                     sessionResponse.error ||
-                     sessionResponse.errorData?.detail ||
-                     sessionResponse.message ||
+    const errorMsg = sessionResponse.formattedError || sessionResponse.error ||
+                     sessionResponse.errorData?.detail || sessionResponse.message ||
                      (sessionResponse.status ? `HTTP ${sessionResponse.status}` : 'Unknown error');
     throw new Error(`Failed to create wizard session: ${errorMsg}`);
   }
-  const sessionId = sessionResponse.data.data?.sessionId || sessionResponse.data.sessionId;
-  if (!sessionId) {
-    throw new Error('Session ID not found in response');
-  }
-  return { mode, sessionId };
+  const sessionId = extractSessionId(sessionResponse.data);
+  return { mode, sessionId, systemIdOrKey };
 }
 
 /**
- * Handle source selection step - update wizard session
+ * Handle interactive source selection step
  * @async
- * @function handleSourceSelection
+ * @function handleInteractiveSourceSelection
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {string} sessionId - Wizard session ID
  * @param {Object} authConfig - Authentication configuration
  * @returns {Promise<Object>} Object with sourceType and sourceData
- * @throws {Error} If source selection fails
  */
-async function handleSourceSelection(dataplaneUrl, sessionId, authConfig) {
-  logger.log(chalk.blue('\n📋 Step 2: Source Selection'));
+async function handleInteractiveSourceSelection(dataplaneUrl, sessionId, authConfig) {
+  logger.log(chalk.blue('\n\uD83D\uDCCB Step 2: Source Selection'));
   const sourceType = await promptForSourceType();
   let sourceData = null;
   const updateData = { currentStep: 1 };
 
   if (sourceType === 'openapi-file') {
-    const filePath = await promptForOpenApiFile();
-    sourceData = filePath;
+    sourceData = await promptForOpenApiFile();
   } else if (sourceType === 'openapi-url') {
-    const url = await promptForOpenApiUrl();
-    sourceData = url;
-    updateData.openapiSpec = null; // Will be set after parsing
+    sourceData = await promptForOpenApiUrl();
+    updateData.openapiSpec = null;
   } else if (sourceType === 'mcp-server') {
     const mcpDetails = await promptForMcpServer();
     sourceData = JSON.stringify(mcpDetails);
     updateData.mcpServerUrl = mcpDetails.url || null;
   } else if (sourceType === 'known-platform') {
-    const platform = await promptForKnownPlatform();
-    sourceData = platform;
+    sourceData = await promptForKnownPlatform();
   }
 
   const updateResponse = await updateWizardSession(dataplaneUrl, sessionId, authConfig, updateData);
@@ -138,185 +114,53 @@ async function handleSourceSelection(dataplaneUrl, sessionId, authConfig) {
 }
 
 /**
- * Parse OpenAPI file
- * @async
- * @function parseOpenApiFile
- * @param {string} dataplaneUrl - Dataplane URL
- * @param {Object} authConfig - Authentication configuration
- * @param {string} sourceData - Source data (file path)
- * @returns {Promise<Object>} OpenAPI spec
- * @throws {Error} If parsing fails
- */
-async function parseOpenApiFile(dataplaneUrl, authConfig, sourceData) {
-  logger.log(chalk.blue('\n📋 Step 3: Parsing OpenAPI File'));
-  const spinner = ora('Parsing OpenAPI file...').start();
-  try {
-    const parseResponse = await parseOpenApi(dataplaneUrl, authConfig, sourceData);
-    spinner.stop();
-    if (!parseResponse.success) {
-      throw new Error(`OpenAPI parsing failed: ${parseResponse.error || parseResponse.formattedError}`);
-    }
-    logger.log(chalk.green('✓ OpenAPI file parsed successfully'));
-    return parseResponse.data?.spec;
-  } catch (error) {
-    spinner.stop();
-    throw error;
-  }
-}
-
-/**
- * Handle OpenAPI parsing step
+ * Handle interactive configuration generation step
  * @async
- * @function handleOpenApiParsing
- * @param {string} dataplaneUrl - Dataplane URL
- * @param {Object} authConfig - Authentication configuration
- * @param {string} sourceType - Source type
- * @param {string} sourceData - Source data
- * @returns {Promise<Object|null>} OpenAPI spec or null
- * @throws {Error} If parsing fails
+ * @function handleInteractiveConfigGeneration
+ * @param {Object} options - Configuration options
+ * @param {string} options.dataplaneUrl - Dataplane URL
+ * @param {Object} options.authConfig - Authentication configuration
+ * @param {string} options.mode - Selected mode
+ * @param {Object} options.openapiSpec - OpenAPI specification
+ * @param {Object} options.detectedType - Detected type info
+ * @param {string} [options.credentialIdOrKey] - Credential ID or key (optional)
+ * @param {string} [options.systemIdOrKey] - System ID or key (optional)
+ * @returns {Promise<Object>} Generated configuration
  */
-async function handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, sourceData) {
-  if (sourceType === 'openapi-file') {
-    return await parseOpenApiFile(dataplaneUrl, authConfig, sourceData);
-  }
-  if (sourceType === 'openapi-url') {
-    logger.log(chalk.blue('\n📋 Step 3: Parsing OpenAPI URL'));
-    logger.log(chalk.green('✓ OpenAPI URL processed'));
-    return null;
-  }
-  return null;
-}
-
-/**
- * Handle type detection step
- * @async
- * @function handleTypeDetection
- * @param {string} dataplaneUrl - Dataplane URL
- * @param {Object} authConfig - Authentication configuration
- * @param {Object} openApiSpec - OpenAPI specification
- * @returns {Promise<Object|null>} Detected type or null
- */
-async function handleTypeDetection(dataplaneUrl, authConfig, openApiSpec) {
-  if (!openApiSpec) {
-    return null;
-  }
-
-  logger.log(chalk.blue('\n📋 Step 4: Detecting API Type'));
-  const spinner = ora('Detecting API type...').start();
-  try {
-    const detectResponse = await detectType(dataplaneUrl, authConfig, openApiSpec);
-    spinner.stop();
-    if (detectResponse.success && detectResponse.data) {
-      const detectedType = detectResponse.data;
-      logger.log(chalk.green(`✓ API type detected: ${detectedType.apiType || 'unknown'}`));
-      if (detectedType.category) {
-        logger.log(chalk.gray(`  Category: ${detectedType.category}`));
-      }
-      return detectedType;
-    }
-  } catch (error) {
-    spinner.stop();
-    logger.log(chalk.yellow(`⚠ Type detection failed: ${error.message}`));
-  }
-  return null;
-}
-
-/**
- * Handle configuration generation step
- * @async
- * @function handleConfigurationGeneration
- * @param {string} dataplaneUrl - Dataplane URL
- * @param {Object} authConfig - Authentication configuration
- * @param {string} mode - Selected mode
- * @param {string} sourceType - Source type
- * @param {Object} openApiSpec - OpenAPI specification
- * @returns {Promise<Object>} Generated configuration with systemConfig, datasourceConfigs, and systemKey
- * @throws {Error} If generation fails
- */
-async function handleConfigurationGeneration(dataplaneUrl, authConfig, mode, sourceType, openApiSpec) {
-  logger.log(chalk.blue('\n📋 Step 5: User Preferences'));
+async function handleInteractiveConfigGeneration(options) {
+  logger.log(chalk.blue('\n\uD83D\uDCCB Step 5: User Preferences'));
   const userIntent = await promptForUserIntent();
   const preferences = await promptForUserPreferences();
 
-  logger.log(chalk.blue('\n📋 Step 6: Generating Configuration'));
-  const spinner = ora('Generating configuration via AI (this may take 10-30 seconds)...').start();
-  try {
-    const generateResponse = await generateConfig(dataplaneUrl, authConfig, {
-      mode,
-      sourceType,
-      openApiSpec,
-      userIntent,
-      preferences
-    });
-    spinner.stop();
-    if (!generateResponse.success) {
-      throw new Error(`Configuration generation failed: ${generateResponse.error || generateResponse.formattedError}`);
-    }
-
-    const systemConfig = generateResponse.data?.systemConfig;
-    const datasourceConfigs = generateResponse.data?.datasourceConfigs || [];
-    const systemKey = generateResponse.data?.systemKey;
-
-    if (!systemConfig) {
-      throw new Error('System configuration not found in generation response');
-    }
-
-    logger.log(chalk.green('✓ Configuration generated successfully'));
-    return { systemConfig, datasourceConfigs, systemKey };
-  } catch (error) {
-    spinner.stop();
-    throw error;
-  }
+  const configPrefs = {
+    intent: userIntent,
+    enableMCP: preferences.mcp,
+    enableABAC: preferences.abac,
+    enableRBAC: preferences.rbac
+  };
+
+  return await handleConfigurationGeneration(options.dataplaneUrl, options.authConfig, {
+    mode: options.mode,
+    openapiSpec: options.openapiSpec,
+    detectedType: options.detectedType,
+    configPrefs,
+    credentialIdOrKey: options.credentialIdOrKey,
+    systemIdOrKey: options.systemIdOrKey
+  });
 }
 
 /**
- * Validate wizard configuration
- * @async
- * @function validateWizardConfiguration
- * @param {string} dataplaneUrl - Dataplane URL
- * @param {Object} authConfig - Authentication configuration
- * @param {Object} systemConfig - System configuration
- * @param {Object[]} datasourceConfigs - Datasource configurations
- * @throws {Error} If validation fails
- */
-async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs) {
-  const validateSpinner = ora('Validating configuration...').start();
-  try {
-    const validateResponse = await validateWizardConfig(dataplaneUrl, authConfig, systemConfig, datasourceConfigs);
-    validateSpinner.stop();
-    if (!validateResponse.success || !validateResponse.data?.valid) {
-      const errors = validateResponse.data?.errors || [];
-      const errorMsg = errors.length > 0
-        ? errors.map(e => e.message || e).join(', ')
-        : validateResponse.error || validateResponse.formattedError || 'Validation failed';
-      throw new Error(`Configuration validation failed: ${errorMsg}`);
-    }
-    logger.log(chalk.green('✓ Configuration validated successfully'));
-    if (validateResponse.data?.warnings && validateResponse.data.warnings.length > 0) {
-      logger.log(chalk.yellow('\n⚠ Warnings:'));
-      validateResponse.data.warnings.forEach(warning => {
-        logger.log(chalk.yellow(`  - ${warning.message || warning}`));
-      });
-    }
-  } catch (error) {
-    validateSpinner.stop();
-    throw error;
-  }
-}
-
-/**
- * Handle configuration review and validation step
+ * Handle configuration review and validation step (interactive mode only)
  * @async
  * @function handleConfigurationReview
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
  * @param {Object} systemConfig - System configuration
  * @param {Object[]} datasourceConfigs - Datasource configurations
- * @returns {Promise<Object>} Final configurations with systemConfig and datasourceConfigs
- * @throws {Error} If validation fails
+ * @returns {Promise<Object>} Final configurations
  */
 async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig, datasourceConfigs) {
-  logger.log(chalk.blue('\n📋 Step 7: Review & Validate'));
+  logger.log(chalk.blue('\n\uD83D\uDCCB Step 6-7: Review & Validate'));
   const reviewResult = await promptForConfigReview(systemConfig, datasourceConfigs);
 
   if (reviewResult.action === 'cancel') {
@@ -324,97 +168,55 @@ async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig,
     return null;
   }
 
-  // Use edited configs if user edited them
   const finalSystemConfig = reviewResult.systemConfig || systemConfig;
   const finalDatasourceConfigs = reviewResult.datasourceConfigs || datasourceConfigs;
 
-  // Validate configuration
   await validateWizardConfiguration(dataplaneUrl, authConfig, finalSystemConfig, finalDatasourceConfigs);
 
   return { systemConfig: finalSystemConfig, datasourceConfigs: finalDatasourceConfigs };
 }
 
 /**
- * Handle file saving step
- * @async
- * @function handleFileSaving
- * @param {string} appName - Application name
- * @param {Object} systemConfig - System configuration
- * @param {Object[]} datasourceConfigs - Datasource configurations
- * @param {string} systemKey - System key
- * @param {string} dataplaneUrl - Dataplane URL
- * @param {Object} authConfig - Authentication configuration
- * @returns {Promise<Object>} Generated files information
- * @throws {Error} If file saving fails
- */
-async function handleFileSaving(appName, systemConfig, datasourceConfigs, systemKey, dataplaneUrl, authConfig) {
-  logger.log(chalk.blue('\n📋 Step 8: Saving Files'));
-  const saveSpinner = ora('Saving files...').start();
-  try {
-    let aiGeneratedReadme = null;
-    if (systemKey && dataplaneUrl && authConfig) {
-      try {
-        const docsResponse = await getDeploymentDocs(dataplaneUrl, authConfig, systemKey);
-        if (docsResponse.success && docsResponse.data?.content) {
-          aiGeneratedReadme = docsResponse.data.content;
-          logger.log(chalk.gray('  ✓ Fetched AI-generated README.md from dataplane'));
-        }
-      } catch (error) {
-        logger.log(chalk.gray(`  ⚠ Could not fetch AI-generated README: ${error.message}`));
-      }
-    }
-    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme });
-    saveSpinner.stop();
-    logger.log(chalk.green('\n✓ Wizard completed successfully!'));
-    logger.log(chalk.green(`\nFiles created in: ${generatedFiles.appPath}`));
-    logger.log(chalk.blue('\nNext steps:'));
-    [`  1. Review the generated files in integration/${appName}/`, '  2. Update env.template with your authentication details', `  3. Deploy using: ./deploy.sh or .\\deploy.ps1 (or aifabrix deploy ${appName})`].forEach(step => logger.log(chalk.gray(step)));
-    return generatedFiles;
-  } catch (error) {
-    saveSpinner.stop();
-    throw error;
-  }
-}
-
-/**
- * Execute wizard flow steps
+ * Execute wizard flow steps (interactive mode)
  * @async
  * @function executeWizardFlow
  * @param {string} appName - Application name
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
  * @returns {Promise<void>} Resolves when wizard flow completes
- * @throws {Error} If wizard flow fails
  */
 async function executeWizardFlow(appName, dataplaneUrl, authConfig) {
-  // Step 1: Mode Selection - Create wizard session
-  const { mode, sessionId } = await handleModeSelection(dataplaneUrl, authConfig);
+  // Step 1: Mode Selection
+  const { mode, sessionId, systemIdOrKey } = await handleInteractiveModeSelection(dataplaneUrl, authConfig);
 
-  // Step 2: Source Selection - Update session
-  const { sourceType, sourceData } = await handleSourceSelection(dataplaneUrl, sessionId, authConfig);
+  // Step 2: Source Selection
+  const { sourceType, sourceData } = await handleInteractiveSourceSelection(dataplaneUrl, sessionId, authConfig);
 
-  // Step 3: Parse OpenAPI (if applicable)
-  const openApiSpec = await handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, sourceData);
+  // Parse OpenAPI (part of step 2)
+  const openapiSpec = await handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, sourceData);
 
-  // Step 4: Detect Type (optional, if OpenAPI spec available)
-  await handleTypeDetection(dataplaneUrl, authConfig, openApiSpec);
+  // Step 3: Credential Selection (optional)
+  const credentialIdOrKey = await handleCredentialSelection(dataplaneUrl, authConfig);
 
-  // Step 5-6: Generate Configuration
-  const { systemConfig, datasourceConfigs, systemKey } = await handleConfigurationGeneration(
+  // Step 4: Detect Type
+  const detectedType = await handleTypeDetection(dataplaneUrl, authConfig, openapiSpec);
+
+  // Step 5: Generate Configuration
+  const { systemConfig, datasourceConfigs, systemKey } = await handleInteractiveConfigGeneration({
     dataplaneUrl,
     authConfig,
     mode,
-    sourceType,
-    openApiSpec
-  );
+    openapiSpec,
+    detectedType,
+    credentialIdOrKey,
+    systemIdOrKey
+  });
 
-  // Step 7: Review & Validate
+  // Step 6-7: Review & Validate
   const finalConfigs = await handleConfigurationReview(dataplaneUrl, authConfig, systemConfig, datasourceConfigs);
-  if (!finalConfigs) {
-    return; // User cancelled
-  }
+  if (!finalConfigs) return;
 
-  // Step 8: Save Files
+  // Step 7: Save Files
   await handleFileSaving(
     appName,
     finalConfigs.systemConfig,
@@ -434,11 +236,17 @@ async function executeWizardFlow(appName, dataplaneUrl, authConfig) {
  * @param {string} [options.controller] - Controller URL
  * @param {string} [options.environment] - Environment key
  * @param {string} [options.dataplane] - Dataplane URL (overrides controller lookup)
+ * @param {string} [options.config] - Path to wizard.yaml config file (headless mode)
  * @returns {Promise<void>} Resolves when wizard completes
  * @throws {Error} If wizard fails
  */
 async function handleWizard(options = {}) {
-  logger.log(chalk.blue('\n🧙 AI Fabrix External System Wizard\n'));
+  // Check if headless mode (config file provided)
+  if (options.config) {
+    return await handleWizardHeadless(options);
+  }
+
+  logger.log(chalk.blue('\n\uD83E\uDDD9 AI Fabrix External System Wizard\n'));
 
   // Get or prompt for app name
   let appName = options.app;
@@ -447,7 +255,7 @@ async function handleWizard(options = {}) {
   }
 
   // Validate app name and check directory
-  const shouldContinue = await validateAndCheckAppDirectory(appName);
+  const shouldContinue = await validateAndCheckAppDirectory(appName, true);
   if (!shouldContinue) {
     return;
   }
@@ -459,34 +267,4 @@ async function handleWizard(options = {}) {
   await executeWizardFlow(appName, dataplaneUrl, authConfig);
 }
 
-/**
- * Setup dataplane URL and authentication
- * @async
- * @function setupDataplaneAndAuth
- * @param {Object} options - Command options
- * @param {string} appName - Application name
- * @returns {Promise<Object>} Object with dataplaneUrl and authConfig
- * @throws {Error} If setup fails
- */
-async function setupDataplaneAndAuth(options, appName) {
-  const configData = await config.getConfig();
-  const environment = options.environment || 'dev';
-  const controllerUrl = await resolveControllerUrl(options, configData);
-  // Wizard requires device token authentication (user-level), not client credentials
-  const authConfig = await getDeviceOnlyAuth(controllerUrl);
-
-  let dataplaneUrl = options.dataplane;
-  if (!dataplaneUrl) {
-    logger.log(chalk.blue('🌐 Getting dataplane URL from controller...'));
-    try {
-      dataplaneUrl = await getDataplaneUrl(controllerUrl, 'dataplane', environment, authConfig);
-      logger.log(chalk.green(`✓ Dataplane URL: ${dataplaneUrl}`));
-    } catch (error) {
-      const example = `aifabrix wizard -a ${appName} --dataplane https://dataplane.example.com -e ${environment} -c ${controllerUrl}`;
-      throw new Error(`${error.message}\n\n💡 For new applications, provide the dataplane URL using:\n   --dataplane <dataplane-url>\n\n   Example: ${example}`);
-    }
-  }
-
-  return { dataplaneUrl, authConfig };
-}
-module.exports = { handleWizard };
+module.exports = { handleWizard, handleWizardHeadless };

package/lib/core/config.js

@@ -95,6 +95,8 @@ function applyConfigDefaults(config) {
   if (typeof config.device !== 'object' || config.device === null) {
     config.device = {};
   }
+  // Ensure controller field exists (but don't set defaults)
+  // It will be set by login or auth config commands
   return config;
 }
 
@@ -107,6 +109,7 @@ function getDefaultConfig() {
   return {
     'developer-id': '0',
     environment: 'dev',
+    controller: undefined,
     environments: {},
     device: {}
   };
@@ -239,6 +242,17 @@ async function getCurrentEnvironment() {
   return config.environment || 'dev';
 }
 
+/**
+ * Resolve environment from configuration
+ * Uses config.environment, defaults to 'dev'
+ * @async
+ * @function resolveEnvironment
+ * @returns {Promise<string>} Environment key
+ */
+async function resolveEnvironment() {
+  return await getCurrentEnvironment();
+}
+
 async function setCurrentEnvironment(environment) {
   if (!environment || typeof environment !== 'string') {
     throw new Error('Environment must be a non-empty string');
@@ -248,6 +262,35 @@ async function setCurrentEnvironment(environment) {
   await saveConfig(config);
 }
 
+/**
+ * Set controller URL in configuration
+ * @async
+ * @function setControllerUrl
+ * @param {string} controllerUrl - Controller URL to save
+ * @returns {Promise<void>}
+ * @throws {Error} If controller URL is invalid
+ */
+async function setControllerUrl(controllerUrl) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('Controller URL is required and must be a string');
+  }
+  const normalizedUrl = normalizeControllerUrl(controllerUrl);
+  const config = await getConfig();
+  config.controller = normalizedUrl;
+  await saveConfig(config);
+}
+
+/**
+ * Get controller URL from configuration
+ * @async
+ * @function getControllerUrl
+ * @returns {Promise<string|null>} Controller URL or null if not set
+ */
+async function getControllerUrl() {
+  const config = await getConfig();
+  return config.controller || null;
+}
+
 function isTokenExpired(expiresAt) {
   if (!expiresAt) return true;
   const expirationTime = new Date(expiresAt).getTime();
@@ -354,6 +397,7 @@ const exportsObj = {
   loadDeveloperId,
   getCurrentEnvironment,
   setCurrentEnvironment,
+  resolveEnvironment,
   isTokenExpired,
   shouldRefreshToken,
   encryptTokenValue,
@@ -363,6 +407,8 @@ const exportsObj = {
   getSecretsPath,
   setSecretsPath,
   normalizeControllerUrl,
+  setControllerUrl,
+  getControllerUrl,
   CONFIG_DIR,
   CONFIG_FILE
 };