configorama 0.6.9 → 0.6.10

package/src/utils/configWizard.js

@@ -0,0 +1,567 @@
+// Wizard to prompt user through config setup
+const p = require('@clack/prompts')
+const chalk = require('./chalk')
+const dotProp = require('dot-prop')
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * Groups variables by type for wizard flow
+ * @param {object} uniqueVariables - The uniqueVariables from enriched metadata
+ * @param {object} originalConfig - The original config before resolution
+ * @returns {object} Grouped variables by type
+ */
+function groupVariablesByType(uniqueVariables, originalConfig = {}) {
+  const grouped = {
+    options: [],
+    env: [],
+    self: [],
+  }
+
+  // Track variables we've already added to avoid duplicates
+  const addedVars = new Set()
+
+  for (const [varKey, varData] of Object.entries(uniqueVariables)) {
+    const { variable, variableType, isRequired, defaultValue, defaultValueSrc, occurrences, innerVariables, hasValue } = varData
+
+    // Handle top-level variables (not file/text types)
+    if (variableType !== 'file' && variableType !== 'text') {
+      // Skip if has a value (for self refs and dot.prop)
+      if (hasValue === true) {
+        continue
+      }
+
+      // For self/dot.prop refs, skip if they have a defaultValueSrc (means they have a static value in config)
+      if ((variableType === 'self' || variableType === 'dot.prop') && defaultValueSrc) {
+        continue
+      }
+
+      // For self/dot.prop refs, skip if ANY occurrence has a fallback
+      // This means the variable has a fallback chain and will resolve naturally
+      if (variableType === 'self' || variableType === 'dot.prop') {
+        const hasAnyFallback = occurrences.some(occ => occ.hasFallback)
+        if (hasAnyFallback) {
+          continue
+        }
+
+        // Skip if this variable only appears as part of another variable's fallback chain
+        // (i.e., appears in 'value' field but not as 'originalString')
+        const isOnlyFallback = occurrences.every(occ => {
+          // If it has originalString, it's a top-level variable
+          if (occ.originalString) return false
+          // If it appears in a 'value' field, it's part of a fallback chain
+          if (occ.value && occ.value.includes(',')) return true
+          return false
+        })
+        if (isOnlyFallback) {
+          continue
+        }
+
+        // Skip if the variable path itself contains unresolved variables
+        // e.g., self:stages.${opt:stage}.SECRET - can't set this in config because path is dynamic
+        const cleanPath = variable.replace(/^self:/, '')
+        if (cleanPath.includes('${')) {
+          continue
+        }
+
+        // Also check if value exists in original config
+        const configValue = dotProp.get(originalConfig, cleanPath)
+        if (configValue !== undefined) {
+          // Value exists in config, skip prompting
+          continue
+        }
+      }
+
+      const cleanName = variable.replace(/^(opt|env|self):/, '')
+
+      if (!addedVars.has(variable)) {
+        addedVars.add(variable)
+
+        // Check if ANY occurrence is required without fallback
+        const hasRequiredOccurrence = occurrences.some(occ => occ.isRequired && !occ.hasFallback)
+
+        // Check if ANY occurrence has a default/fallback value
+        const fallbackOccurrence = occurrences.find(occ => occ.hasFallback && occ.defaultValue)
+        const availableDefault = fallbackOccurrence?.defaultValue || defaultValue
+
+        const varInfo = {
+          key: varKey,
+          variable,
+          cleanName,
+          variableType,
+          isRequired: hasRequiredOccurrence,
+          defaultValue: availableDefault,
+          hasFallback: !!availableDefault,
+          occurrences: occurrences || [],
+        }
+
+        if (variableType === 'options') {
+          grouped.options.push(varInfo)
+        } else if (variableType === 'env') {
+          grouped.env.push(varInfo)
+        } else if (variableType === 'self') {
+          grouped.self.push(varInfo)
+        }
+      }
+    }
+
+    // Extract inner variables from file/text references
+    if (innerVariables && Array.isArray(innerVariables)) {
+      for (const innerVar of innerVariables) {
+        // Skip if already has a value
+        if (innerVar.hasValue) {
+          continue
+        }
+
+        // Skip if not required
+        if (!innerVar.isRequired) {
+          continue
+        }
+
+        const cleanName = innerVar.variable.replace(/^(opt|env|self):/, '')
+
+        // If already added, append this occurrence to existing variable
+        const existingVarIndex = grouped[innerVar.variableType === 'options' ? 'options' : innerVar.variableType === 'env' ? 'env' : 'self']
+          .findIndex(v => v.variable === innerVar.variable)
+
+        if (existingVarIndex >= 0) {
+          // Add this occurrence to the existing variable
+          const varList = innerVar.variableType === 'options' ? grouped.options : innerVar.variableType === 'env' ? grouped.env : grouped.self
+          const existingVar = varList[existingVarIndex]
+
+          // Add occurrence from parent file variable
+          if (occurrences && occurrences.length > 0) {
+            existingVar.occurrences.push(...occurrences)
+          }
+          continue
+        }
+
+        // Skip if already added to the set
+        if (addedVars.has(innerVar.variable)) {
+          continue
+        }
+
+        addedVars.add(innerVar.variable)
+
+        const varInfo = {
+          key: innerVar.variable,
+          variable: innerVar.variable,
+          cleanName,
+          variableType: innerVar.variableType,
+          isRequired: innerVar.isRequired,
+          defaultValue: innerVar.defaultValue,
+          occurrences: occurrences ? [...occurrences] : [], // Use parent file variable occurrences
+        }
+
+        if (innerVar.variableType === 'options') {
+          grouped.options.push(varInfo)
+        } else if (innerVar.variableType === 'env') {
+          grouped.env.push(varInfo)
+        } else if (innerVar.variableType === 'self') {
+          grouped.self.push(varInfo)
+        }
+      }
+    }
+  }
+
+  return grouped
+}
+
+/**
+ * Detects if a variable name suggests sensitive data
+ * @param {string} name - Variable name
+ * @returns {boolean} True if likely sensitive
+ */
+function isSensitiveVariable(name) {
+  const sensitivePatterns = [
+    /secret/i,
+    /password/i,
+    /token/i,
+    /key/i,
+    /credential/i,
+    /auth/i,
+  ]
+  return sensitivePatterns.some(pattern => pattern.test(name))
+}
+
+/**
+ * Validates input value based on expected type
+ * @param {string} value - Input value
+ * @param {string} expectedType - Expected type (String, Number, Boolean, Json)
+ * @returns {string|undefined} Error message if invalid, undefined if valid
+ */
+function validateType(value, expectedType) {
+  if (!expectedType || !value) return
+
+  switch (expectedType) {
+    case 'Boolean':
+      const lowerVal = value.toLowerCase()
+      const validBooleans = ['true', 'false', 'yes', 'no', 'on', 'off', '1', '0']
+      if (!validBooleans.includes(lowerVal)) {
+        return `Must be a boolean value (true/false, yes/no, on/off, 1/0)`
+      }
+      break
+
+    case 'Number':
+      if (isNaN(Number(value))) {
+        return `Must be a valid number`
+      }
+      break
+
+    case 'Json':
+      try {
+        JSON.parse(value)
+      } catch (e) {
+        return `Must be valid JSON`
+      }
+      break
+
+    case 'String':
+      // String is always valid
+      break
+  }
+}
+
+/**
+ * Extracts type from variable occurrences
+ * @param {Array} occurrences - Variable occurrences
+ * @returns {string|null} Expected type or null
+ */
+function getExpectedType(occurrences) {
+  if (!occurrences || occurrences.length === 0) return null
+
+  for (const occ of occurrences) {
+    if (occ.filters && Array.isArray(occ.filters)) {
+      for (const filter of occ.filters) {
+        // Check if filter starts with uppercase letter
+        if (filter && typeof filter === 'string' && /^[A-Z]/.test(filter)) {
+          return filter
+        }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Extracts help text from variable occurrences
+ * @param {Array} occurrences - Variable occurrences
+ * @returns {string|null} Help text or null
+ */
+function getHelpText(occurrences) {
+  if (!occurrences || occurrences.length === 0) return null
+
+  for (const occ of occurrences) {
+    // Check for description field first (preferred)
+    if (occ.description) {
+      return occ.description
+    }
+
+    // Fallback to checking filters array (for backwards compatibility)
+    if (occ.filters && Array.isArray(occ.filters)) {
+      for (const filter of occ.filters) {
+        // Check if filter has help() syntax
+        const helpMatch = filter.match(/^help\(['"](.+)['"]\)$/)
+        if (helpMatch) {
+          return helpMatch[1]
+        }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Creates a human-readable prompt message
+ * @param {object} varInfo - Variable info
+ * @returns {string} Prompt message
+ */
+function createPromptMessage(varInfo) {
+  const { cleanName, variableType, occurrences } = varInfo
+
+  let typeLabel
+  if (variableType === 'options') {
+    typeLabel = 'Flag'
+  } else if (variableType === 'env') {
+    typeLabel = 'Env'
+  } else if (variableType === 'self') {
+    typeLabel = 'Config'
+  } else {
+    typeLabel = 'Value'
+  }
+
+  // Check for type from filters
+  const expectedType = getExpectedType(occurrences)
+
+  // Append type to label if found
+  if (expectedType) {
+    typeLabel = `${typeLabel}:${expectedType}`
+  }
+
+  // Collect all unique descriptions from occurrences
+  const descriptions = []
+  if (occurrences && occurrences.length > 0) {
+    occurrences.forEach(occ => {
+      if (occ.description && !descriptions.includes(occ.description)) {
+        descriptions.push(occ.description)
+      }
+    })
+  }
+
+  // Build context from all occurrences
+  let contextHint = ''
+
+  // Show combined descriptions if available
+  if (descriptions.length > 0) {
+    contextHint = ` - ${descriptions.join('. ')}`
+  }
+
+  // Show usage list if there are occurrences
+  if (occurrences && occurrences.length > 0) {
+    // Parse occurrences into key-value pairs with descriptions
+    const parsedOccurrences = occurrences.map(occ => {
+      const keyPath = occ.path
+      let originalValue = occ.value || occ.originalString || occ.varMatch
+
+      // Strip help() filter from the displayed value
+      if (originalValue && typeof originalValue === 'string') {
+        // Remove | help('...') including nested parens
+        originalValue = originalValue.replace(/\s*\|\s*help\([^)]*(?:\([^)]*\))?[^)]*\)/g, '')
+      }
+
+      if (keyPath && originalValue) {
+        return {
+          key: keyPath,
+          value: originalValue,
+          description: occ.description
+        }
+      } else if (keyPath) {
+        return {
+          key: keyPath,
+          value: '',
+          description: occ.description
+        }
+      }
+      return null
+    }).filter(Boolean)
+
+    if (parsedOccurrences.length > 0) {
+      // Get the variable reference syntax
+      const varPrefix = variableType === 'options' ? 'opt' : variableType === 'env' ? 'env' : 'self'
+      const varSyntax = `\${${varPrefix}:${cleanName}}`
+
+      // Show variable syntax and count (only if no descriptions, otherwise it's redundant)
+      if (descriptions.length === 0) {
+        contextHint = ` - ${varSyntax} - Used in ${parsedOccurrences.length} ${parsedOccurrences.length === 1 ? 'place' : 'places'}`
+      }
+
+      // Find longest key for alignment
+      const maxKeyLength = Math.max(...parsedOccurrences.map(o => o.key.length))
+
+      // List all occurrences with bullets and aligned values (using invisible unicode for indentation)
+      const indent = '\u2800\u2800\u2800' // Braille blank pattern (invisible but not stripped)
+      const usageList = parsedOccurrences.map(({ key, value, description }, index) => {
+        const padding = ' '.repeat(maxKeyLength - key.length)
+        const leadingEmptyLine = index === 0 ? '│\n' : ''
+        // Only show inline description if there are multiple occurrences (otherwise it's redundant with header)
+        const descComment = description && parsedOccurrences.length > 1 ? ` - # ${description}` : ''
+        return value ? `${leadingEmptyLine}│${indent}- ${key}:${padding}    ${value}${descComment}` : `${leadingEmptyLine}│${indent}• ${key}${descComment}`
+      })
+      contextHint += '\n' + usageList.join('\n') + '\n│'
+    }
+  }
+
+  const message = `[${typeLabel}] ${cleanName}${chalk.gray(contextHint)}`
+
+  return message
+}
+
+/**
+ * Runs config setup wizard
+ * @param {object} metadata - Enriched metadata from configorama
+ * @param {object} originalConfig - The original config before resolution
+ * @returns {Promise<object>} User inputs by variable type
+ */
+async function runConfigWizard(metadata, originalConfig = {}, configFilePath = '') {
+  const { uniqueVariables } = metadata
+
+  if (!uniqueVariables || Object.keys(uniqueVariables).length === 0) {
+    p.intro(chalk.cyan('Configuration Wizard'))
+    if (configFilePath) {
+      p.note(`File: ${configFilePath}`, 'File')
+    }
+    p.outro('No variables found that require setup.')
+    return {}
+  }
+
+  const grouped = groupVariablesByType(uniqueVariables, originalConfig)
+  const totalVars = grouped.options.length + grouped.env.length + grouped.self.length
+
+  if (totalVars === 0) {
+    p.intro(chalk.cyan('Configuration Wizard'))
+    p.outro('No variables found that require setup.')
+    return {}
+  }
+
+  p.intro(chalk.cyan('Configuration Wizard'))
+  if (configFilePath) {
+    p.note(`Processing config file: ${configFilePath}`)
+  }
+
+  const userInputs = {
+    options: {},
+    env: {},
+    self: {},
+  }
+
+  // Prompt for options (CLI flags)
+  if (grouped.options.length > 0) {
+    const flagsList = grouped.options.map(v => {
+      const varSyntax = `\${opt:${v.cleanName}}`
+      return `  - ${varSyntax}`
+    }).join('\n')
+    const noteContent = `Found ${grouped.options.length} CLI flag(s)\n${flagsList}`
+    p.note(noteContent, 'CLI Flags')
+
+    for (const varInfo of grouped.options) {
+      const message = createPromptMessage(varInfo)
+      const isSensitive = isSensitiveVariable(varInfo.cleanName)
+      const promptFn = isSensitive ? p.password : p.text
+      const expectedType = getExpectedType(varInfo.occurrences)
+
+      const placeholder = varInfo.hasFallback
+        ? `${varInfo.defaultValue} (default)`
+        : `Enter value for --${varInfo.cleanName}`
+
+      const value = await promptFn({
+        message,
+        placeholder,
+        validate: (val) => {
+          // Only required if no fallback exists
+          if (!val && varInfo.isRequired && !varInfo.hasFallback) {
+            return 'This value is required'
+          }
+          // Type validation
+          const typeError = validateType(val, expectedType)
+          if (typeError) return typeError
+        }
+      })
+
+      if (p.isCancel(value)) {
+        p.cancel('Setup cancelled')
+        process.exit(0)
+      }
+
+      userInputs.options[varInfo.cleanName] = value || varInfo.defaultValue
+    }
+  }
+
+  // Prompt for environment variables
+  if (grouped.env.length > 0) {
+    const envList = grouped.env.map(v => {
+      const varSyntax = `\${env:${v.cleanName}}`
+      return `  - ${varSyntax}`
+    }).join('\n')
+    const noteContent = `Found ${grouped.env.length} environment variable(s)\n${envList}`
+    p.note(noteContent, 'Environment Variables')
+
+    for (const varInfo of grouped.env) {
+      const message = createPromptMessage(varInfo)
+      const isSensitive = isSensitiveVariable(varInfo.cleanName)
+      const promptFn = isSensitive ? p.password : p.text
+      const expectedType = getExpectedType(varInfo.occurrences)
+
+      const placeholder = varInfo.hasFallback
+        ? `${varInfo.defaultValue} (default)`
+        : `Enter environment variable for ${varInfo.cleanName}`
+
+      const value = await promptFn({
+        message,
+        placeholder,
+        validate: (val) => {
+          // Only required if no fallback exists
+          if (!val && varInfo.isRequired && !varInfo.hasFallback) {
+            return 'This value is required'
+          }
+          // Type validation
+          const typeError = validateType(val, expectedType)
+          if (typeError) return typeError
+        }
+      })
+
+      if (p.isCancel(value)) {
+        p.cancel('Setup cancelled')
+        process.exit(0)
+      }
+
+      userInputs.env[varInfo.cleanName] = value || varInfo.defaultValue
+    }
+  }
+
+  // Prompt for self references (if any need values)
+  if (grouped.self.length > 0) {
+    const selfList = grouped.self.map(v => {
+      const varSyntax = `\${self:${v.cleanName}}`
+      return `  - ${varSyntax}`
+    }).join('\n')
+    const noteContent = `Found ${grouped.self.length} config reference(s)\n${selfList}`
+    p.note(noteContent, 'Config References')
+
+    for (const varInfo of grouped.self) {
+      const message = createPromptMessage(varInfo)
+      const isSensitive = isSensitiveVariable(varInfo.cleanName)
+      const promptFn = isSensitive ? p.password : p.text
+      const expectedType = getExpectedType(varInfo.occurrences)
+
+      const placeholder = varInfo.hasFallback
+        ? `${varInfo.defaultValue} (default)`
+        : `Enter value for ${varInfo.cleanName}`
+
+      const value = await promptFn({
+        message,
+        placeholder,
+        validate: (val) => {
+          // Only required if no fallback exists
+          if (!val && varInfo.isRequired && !varInfo.hasFallback) {
+            return 'This value is required'
+          }
+          // Type validation
+          const typeError = validateType(val, expectedType)
+          if (typeError) return typeError
+        }
+      })
+
+      if (p.isCancel(value)) {
+        p.cancel('Setup cancelled')
+        process.exit(0)
+      }
+
+      userInputs.self[varInfo.cleanName] = value || varInfo.defaultValue
+    }
+  }
+
+  p.outro(chalk.green('Setup complete!'))
+
+  // Remove empty sections
+  if (Object.keys(userInputs.options).length === 0) {
+    delete userInputs.options
+  }
+  if (Object.keys(userInputs.env).length === 0) {
+    delete userInputs.env
+  }
+  if (Object.keys(userInputs.self).length === 0) {
+    delete userInputs.self
+  }
+
+  return userInputs
+}
+
+module.exports = {
+  runConfigWizard,
+  groupVariablesByType,
+  isSensitiveVariable,
+  createPromptMessage,
+  getExpectedType,
+  getHelpText,
+  validateType,
+}

package/src/utils/encoders/index.js

@@ -0,0 +1,15 @@
+const { decodeJsSyntax, hasParenthesesPlaceholder } = require('./js-fixes')
+const { decodeUnknown, hasEncodedUnknown } = require('./unknown-values')
+
+// Generic decoder for all encoded values
+function decodeEncodedValue(value) {
+  if (hasParenthesesPlaceholder(value)) {
+    return decodeJsSyntax(value)
+  }
+  if (hasEncodedUnknown(value)) {
+    return decodeUnknown(value)
+  }
+  return value
+}
+
+module.exports = { decodeEncodedValue }

package/src/utils/encoders/js-fixes.js

@@ -0,0 +1,22 @@
+const PAREN_OPEN_PLACEHOLDER = '__PH_PAREN_OPEN__'
+const OPEN_PAREN_PLACEHOLDER_PATTERN = /__PH_PAREN_OPEN__/g
+
+function encodeJsSyntax(value = '') {
+  return value.replace(/\(/g, PAREN_OPEN_PLACEHOLDER)
+}
+
+function decodeJsSyntax(value) {
+  if (!value) return value
+  return value.replace(OPEN_PAREN_PLACEHOLDER_PATTERN, '(')
+}
+
+function hasParenthesesPlaceholder(value = '') {
+  return OPEN_PAREN_PLACEHOLDER_PATTERN.test(value)
+}
+
+module.exports = {
+  OPEN_PAREN_PLACEHOLDER_PATTERN,
+  hasParenthesesPlaceholder,
+  encodeJsSyntax,
+  decodeJsSyntax,
+}

package/src/utils/{unknownValues.js → encoders/unknown-values.js}

@@ -1,3 +1,6 @@
+const PASSTHROUGH_PREFIX = '>passthrough'
+const PASSTHROUGH_PATTERN = />passthrough/g
+
 /**
  * Encode unknown variable for passthrough
  */
@@ -5,12 +8,16 @@ function encodeUnknown(v) {
   return `>passthrough[_[${Buffer.from(v).toString('base64')}]_]`
 }
 
+function hasEncodedUnknown(value) {
+  return PASSTHROUGH_PATTERN.test(value)
+}
+
 /**
  * Decode unknown variable from passthrough
  */
 function decodeUnknown(rawValue) {
   const x = findUnknownValues(rawValue)
-  let val = rawValue.replace(/>passthrough/g, '')
+  let val = rawValue.replace(PASSTHROUGH_PATTERN, '')
   if (x.length) {
     x.forEach(({ match, value }) => {
       const decodedValue = Buffer.from(value, 'base64').toString('ascii')
@@ -40,6 +47,8 @@ function findUnknownValues(text) {
 }
 
 module.exports = {
+  PASSTHROUGH_PATTERN,
+  hasEncodedUnknown,
   encodeUnknown,
   decodeUnknown,
   findUnknownValues