configorama 0.11.2 → 1.0.0

package/src/main.js

@@ -39,7 +39,25 @@ function walkAndUpdate(root, callback) {
   }
   visit(root, [], null, null)
 }
+
+function isNestedFilterArgument(property, matchedString) {
+  if (typeof property !== 'string' || typeof matchedString !== 'string') return false
+  if (property.trim() === matchedString.trim()) return false
+  const matchIdx = property.indexOf(matchedString)
+  const pipeIdx = property.indexOf('|')
+  const openParenIdx = property.lastIndexOf('(', matchIdx)
+  const closeParenIdx = property.indexOf(')', matchIdx)
+  return pipeIdx !== -1 && matchIdx > pipeIdx && openParenIdx > pipeIdx && closeParenIdx > matchIdx
+}
 const dotProp = require('dot-prop')
+
+function resolveStaticFilterArg(arg, config) {
+  const match = String(arg).trim().match(/^\$\{(?:self:)?([^}]+)\}$/)
+  if (!match) return arg
+  if (!dotProp.has(config, match[1])) return arg
+  return encodeFilterArg(dotProp.get(config, match[1]))
+}
+
 /* Utils - root */
 const {
   isArray, isString, isNumber, isObject, isDate, isRegExp, isFunction,
@@ -71,17 +89,28 @@ const { replaceAll } = require('./utils/strings/replaceAll')
 const { getTextAfterOccurrence, findNestedVariable } = require('./utils/strings/textUtils')
 const { ensureQuote, isSurroundedByQuotes, startsWithQuotedPipe } = require('./utils/strings/quoteUtils')
 const { splitOnPipe } = require('./utils/strings/splitOnPipe')
+const { encodeFilterArg } = require('./utils/filters/filterArgs')
+const { validateOneOf } = require('./utils/filters/oneOf')
 /* Utils - ui */
 const chalk = require('./utils/ui/chalk')
 const deepLog = require('./utils/ui/deep-log')
 const { logHeader } = require('./utils/ui/logs')
 const { runConfigWizard } = require('./utils/ui/configWizard')
+const { buildConfigRequirements } = require('./utils/requirements/configRequirements')
+const { redactUserInputsByRequirements } = require('./utils/redaction/setupRedaction')
 /* Display */
 const { displayNoVariablesFound, displayVariableDetails, displayUniqueVariables, displayConfigurableVariables } = require('./display')
 /* Metadata */
 const { collectVariableMetadata: collectMetadata } = require('./metadata')
 /* Utils - validation */
 const { warnIfNotFound, isValidValue } = require('./utils/validation/warnIfNotFound')
+const {
+  assertCustomFunctionsAllowed,
+  assertCustomResolversAllowed,
+  assertSafeConfigInput,
+  normalizeSafetyPolicy,
+} = require('./utils/security/safetyPolicy')
+const { ConfigoramaError } = require('./errors')
 /* Utils - variables */
 const cleanVariable = require('./utils/variables/cleanVariable')
 const appendDeepVariable = require('./utils/variables/appendDeepVariable')
@@ -144,6 +173,8 @@ class Configorama {
     }
   
     const options = opts || {}
+    // Setup wizard runs when --setup flag is passed (CLI) or options.setup is true (library)
+    this.setupMode = SETUP_MODE || options.setup === true
     // Set opts to pass into JS file calls
     this.settings = Object.assign({}, {
       // Allow unknown ${xyz:...} syntax where xyz is not a registered resolver
@@ -168,6 +199,7 @@ class Configorama {
       // CloudFormation Fn::Sub, inline Lambda code, and CloudFront functions.
       ignorePaths: [],
       skipResolutionPaths: [],
+      safeMode: false,
     }, options)
 
     // Backward compat: allowUnknownVars -> allowUnknownVariableTypes
@@ -179,6 +211,13 @@ class Configorama {
       this.settings.allowUnknownVariableTypes = options.allowUnknownVariables
     }
 
+    this.safetyPolicy = normalizeSafetyPolicy(this.settings, {
+      configDir: options.configDir || (typeof fileOrObject === 'string' ? path.dirname(path.resolve(fileOrObject)) : process.cwd())
+    })
+
+    assertCustomResolversAllowed(options.variableSources, this.safetyPolicy)
+    assertCustomFunctionsAllowed(options.functions, this.safetyPolicy)
+
     // Merge legacy allowUnknownParams and allowUnknownFileRefs into allowUnresolvedVariables
     let unresolvedSetting = this.settings.allowUnresolvedVariables
     if (unresolvedSetting !== true) {
@@ -197,6 +236,9 @@ class Configorama {
     // Paths whose current value is a literal with no variables — skip rebuilding
     // their leaf object on every subsequent populateObjectImpl iteration.
     this._resolvedPaths = new Set()
+    // Ignore-path decisions are constant for a run (patterns are fixed per
+    // instance), so cache per path to skip repeated glob matching.
+    this._ignorePathCache = new Map()
     // Cache raw file contents per absolute path so repeated ${file:...} refs
     // to the same file (e.g., merged twice into different keys) don't reread.
     this._fileContentCache = new Map()
@@ -208,7 +250,7 @@ class Configorama {
     this._needsRawClone = !!(
       this.settings.returnMetadata ||
       this.settings.returnPreResolvedVariableDetails ||
-      VERBOSE || SETUP_MODE || showFound
+      VERBOSE || this.setupMode || showFound
     )
 
     this.foundVariables = []
@@ -272,6 +314,7 @@ class Configorama {
       // Set configPath for file references
       this.configPath = options.configDir || process.cwd()
     } else if (typeof fileOrObject === 'string') {
+      assertSafeConfigInput(fileOrObject, this.safetyPolicy)
       // read and parse file
       const fileContents = fs.readFileSync(fileOrObject, 'utf-8')
       const fileDirectory = path.dirname(path.resolve(fileOrObject))
@@ -502,9 +545,11 @@ class Configorama {
     // Build prefix lookup map for O(1) type detection (perf optimization)
     this._resolverByPrefix = new Map()
     for (const r of this.variableTypes) {
-      const prefix = r.prefix || r.type
-      if (prefix && r.match instanceof RegExp && !r.internal) {
-        this._resolverByPrefix.set(prefix + ':', r)
+      const prefixes = r.prefixes || [r.prefix || r.type]
+      for (const prefix of prefixes) {
+        if (prefix && r.match instanceof RegExp && !r.internal) {
+          this._resolverByPrefix.set(prefix + ':', r)
+        }
       }
     }
 
@@ -575,6 +620,37 @@ class Configorama {
         if (value === undefined || value === null || value === 'null') return ''
         return String(value)
       },
+      Array: (value) => {
+        if (Array.isArray(value)) return value
+        if (typeof value !== 'string') {
+          throw new Error(`Configorama Error: Expected Array, got "${value}"`)
+        }
+        const trimmed = value.trim()
+        if (!trimmed) return []
+        try {
+          const parsed = JSON5.parse(trimmed)
+          if (Array.isArray(parsed)) return parsed
+          throw new Error('not-array')
+        } catch (error) {
+          if (trimmed.includes(',')) {
+            return trimmed.split(',').map(item => item.trim()).filter(Boolean)
+          }
+          throw new Error(`Configorama Error: Expected Array, got "${value}"`)
+        }
+      },
+      Object: (value) => {
+        if (value && typeof value === 'object' && !Array.isArray(value)) return value
+        if (typeof value !== 'string') {
+          throw new Error(`Configorama Error: Expected Object, got "${value}"`)
+        }
+        try {
+          const parsed = JSON5.parse(value)
+          if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed
+        } catch (error) {
+          // Fall through to consistent error below.
+        }
+        throw new Error(`Configorama Error: Expected Object, got "${value}"`)
+      },
       Json: (value) => {
         try {
           return typeof value === 'string' ? JSON.parse(value) : value
@@ -588,6 +664,7 @@ class Configorama {
         // The helpText argument is extracted during metadata collection for the wizard
         return value
       },
+      oneOf: validateOneOf,
     }
 
     // Apply user defined filters
@@ -746,7 +823,7 @@ class Configorama {
         dynamicArgs: this.settings.dynamicArgs
       })
       this.configFileContents = ''
-      if (VERBOSE || showFoundVariables || this.settings.returnPreResolvedVariableDetails || SETUP_MODE) {
+      if (VERBOSE || showFoundVariables || this.settings.returnPreResolvedVariableDetails || this.setupMode) {
         this.configFileContents = fs.readFileSync(this.configFilePath, 'utf8')
       }
       /*
@@ -789,7 +866,7 @@ class Configorama {
     const variableSyntax = this.variableSyntax
     const variablesKnownTypes = this.variablesKnownTypes
 
-    if (VERBOSE || showFoundVariables || this.settings.returnPreResolvedVariableDetails || SETUP_MODE) {
+    if (VERBOSE || showFoundVariables || this.settings.returnPreResolvedVariableDetails || this.setupMode) {
       const metadata = this.collectVariableMetadata()
 
       const enrich = await enrichMetadata(
@@ -844,15 +921,18 @@ class Configorama {
       displayConfigurableVariables(displayParams)
 
 
-      // WALK through CLI prompt if --setup flag is set
-      if (SETUP_MODE) {
+      // WALK through CLI prompt when setup mode is active
+      if (this.setupMode) {
         logHeader('Setup Mode')
         // deepLog('enrich', enrich)
         const userInputs = await runConfigWizard(enrich, this.originalConfig, this.configFilePath)
+        const setupRequirements = buildConfigRequirements(enrich)
+        this.setupRequirements = setupRequirements
+        const displayInputs = redactUserInputsByRequirements(userInputs, setupRequirements)
 
         logHeader('User Inputs Summary')
         console.log()
-        console.log(JSON.stringify(userInputs, null, 2))
+        console.log(JSON.stringify(displayInputs, null, 2))
 
         // TODO set values
 
@@ -902,6 +982,12 @@ class Configorama {
 
     const useDotEnv = this.originalConfig.useDotenv || this.originalConfig.useDotEnv
     if ((useDotEnv && useDotEnv === true) || this.settings.useDotEnvFiles) {
+      if (this.safetyPolicy.blockDotEnv) {
+        throw new ConfigoramaError('blocked_by_safe_mode', 'Dotenv loading is blocked in safe mode', {
+          surface: 'dotenv',
+          configPath: this.configFilePath,
+        })
+      }
       let providerStage
       /* has hardcoded stage */
       if (
@@ -1127,7 +1213,14 @@ class Configorama {
   // ## PROPERTY HANDLING ##
   // #######################
   isIgnorePath(pathValue) {
-    return shouldIgnorePath(pathValue, this.ignorePathPatterns)
+    if (!this.ignorePathPatterns.length) return false
+    // NUL-join so distinct path arrays can never collide on a shared key.
+    const key = isArray(pathValue) ? pathValue.join('\x00') : String(pathValue)
+    const cached = this._ignorePathCache.get(key)
+    if (cached !== undefined) return cached
+    const result = shouldIgnorePath(pathValue, this.ignorePathPatterns)
+    this._ignorePathCache.set(key, result)
+    return result
   }
   // True when the value has a configorama-typed token that resolves even inside an
   // ignore-path (file/text/env/opt/cron/git/custom) — i.e. not just self/CFN refs.
@@ -1808,6 +1901,9 @@ class Configorama {
           valueToPopulate = `"${valueToPopulate}"`
         }
       }
+      if (isNestedFilterArgument(property, currentMatchedString)) {
+        valueToPopulate = encodeFilterArg(valueToPopulate)
+      }
       property = replaceAll(currentMatchedString, valueToPopulate, property)
       // console.log('property replaceAll', property)
 
@@ -1818,7 +1914,10 @@ class Configorama {
     // partial replacement, number
     } else if (isNumber(valueToPopulate)) {
       if (DEBUG_TYPE) console.log('DEBUG_TYPE isNumber')
-      property = replaceAll(matchedString, String(valueToPopulate), property)
+      const replacementValue = isNestedFilterArgument(property, matchedString)
+        ? encodeFilterArg(valueToPopulate)
+        : String(valueToPopulate)
+      property = replaceAll(matchedString, replacementValue, property)
       // TODO This was temp fix for array value mismatch from filters. This fixes filterInner: ${commas | split(${self:inner}, 2) }
       // } else if (isArray(valueToPopulate) && valueToPopulate.length === 1) {
       //  property = replaceAll(matchedString, String(valueToPopulate[0]), property)
@@ -1841,7 +1940,9 @@ class Configorama {
         )
         // Only encode for file() or text() references where JSON braces break regex matching
         const isFileOrTextRef = /\bfile\s*\(|\btext\s*\(/.test(property)
-        if (isNestedInVariable && isFileOrTextRef) {
+        if (isNestedFilterArgument(property, matchedString)) {
+          property = replaceAll(matchedString, encodeFilterArg(valueToPopulate), property)
+        } else if (isNestedInVariable && isFileOrTextRef) {
           // Encode object as base64 to avoid breaking variable syntax with nested braces
           const encodedObj = encodeJsonForVariable(valueToPopulate)
           property = replaceAll(matchedString, encodedObj, property)
@@ -2069,7 +2170,7 @@ Missing Value ${missingValue} - ${matchedString}
           const rawArgs = funcMatch[2]
           if (rawArgs) {
             const splitter = splitCsv(rawArgs, ', ')
-            filterArgs = formatFunctionArgs(splitter)
+            filterArgs = formatFunctionArgs(splitter.map(arg => resolveStaticFilterArg(arg, this.config)))
           }
         }
 
@@ -2515,7 +2616,7 @@ Missing Value ${missingValue} - ${matchedString}
             // Parse arguments using the same logic as functions
             if (rawArgs) {
               const splitter = splitCsv(rawArgs, ', ')
-              filterArgs = formatFunctionArgs(splitter)
+              filterArgs = formatFunctionArgs(splitter.map(arg => resolveStaticFilterArg(arg, this.config)))
             }
           }
 
@@ -2787,7 +2888,8 @@ Missing Value ${missingValue} - ${matchedString}
       textRefSyntax: textRefSyntax,
       varPrefix: this.varPrefix,
       varSuffix: this.varSuffix,
-      fileContentCache: this._fileContentCache
+      fileContentCache: this._fileContentCache,
+      safetyPolicy: this.safetyPolicy
     }
     return getValueFromFileResolver(ctx, variableString, options)
   }

package/src/resolvers/valueFromEval.js

@@ -1,6 +1,7 @@
 // const evalRefSyntax = RegExp(/^eval\((~?[\{\}\:\${}a-zA=>+!-Z0-9._\-\/,'"\*\` ]+?)?\)/g)
 const evalRefSyntax = RegExp(/^eval\((.*)?\)/g)
 const { replaceOutsideQuotes } = require('../utils/strings/quoteAware')
+const { assertSafeEvalExpression } = require('../utils/security/evalSafety')
 
 // Pattern for encoded objects/arrays: __OBJ:base64__ or __ARR:base64__
 const ENCODED_PATTERN = /__(?:OBJ|ARR):([A-Za-z0-9+/=]+)__/g
@@ -52,7 +53,9 @@ async function getValueFromEval(variableString) {
 
   // Use "justin" variant to support strict comparison (===, !==) and other JS-like operators
   try {
-    const { default: subscript } = await import('subscript/justin')
+    // justin re-exports `parse` from subscript; importing the subpath directly
+    // ('subscript/parse') is not resolvable under classic module resolution.
+    const { default: subscript, parse } = await import('subscript/justin')
 
     // Handle string comparisons by ensuring both sides are quoted
     let processedExpression = expression.replace(/([a-zA-Z0-9_]+)\s*([=!<>]=?)\s*['"]([^'"]+)['"]/g, '"$1"$2"$3"')
@@ -79,6 +82,13 @@ async function getValueFromEval(variableString) {
     processedExpression = wrapComparisons(processedExpression)
 
     if (process.env.DEBUG_EVAL) console.log('eval processed:', processedExpression)
+
+    // Block prototype-chain escapes (e.g. "".constructor.constructor) before
+    // compiling, whether or not safe mode is enabled.
+    let ast = null
+    try { ast = parse(processedExpression) } catch (parseError) { ast = null }
+    assertSafeEvalExpression(processedExpression, ast)
+
     const fn = subscript(processedExpression)
     const result = fn(Object.keys(context).length > 0 ? context : undefined)
     return result

package/src/resolvers/valueFromFile.js

@@ -8,6 +8,7 @@ const { resolveFilePathFromMatch, resolveFilePath } = require('../utils/paths/ge
 const { findNestedVariables } = require('../utils/variables/findNestedVariables')
 const { makeBox } = require('@davidwells/box-logger')
 const { encodeJsSyntax, decodeJsonInVariable, hasEncodedJson } = require('../utils/encoders/js-fixes')
+const { checkFileAccess } = require('../utils/security/safetyPolicy')
 
 /* File Parsers */
 const YAML = require('../parsers/yaml')
@@ -109,6 +110,7 @@ function parseFileContents(content, filePath) {
  * @param {string} ctx.varPrefix - Variable prefix (e.g., '${')
  * @param {string} ctx.varSuffix - Variable suffix (e.g., '}')
  * @param {Map<string, string>} [ctx.fileContentCache] - Optional per-instance read cache keyed by absolute file path
+ * @param {object} [ctx.safetyPolicy] - Optional safe-mode policy for executable and root checks
  * @param {string} variableString - The variable string to resolve
  * @param {object} options - Resolution options
  * @returns {Promise<any>}
@@ -187,6 +189,9 @@ async function getValueFromFile(ctx, variableString, options) {
   }
 
   const exists = fs.existsSync(fullFilePath)
+  if (ctx.safetyPolicy) {
+    checkFileAccess(fullFilePath, ctx.safetyPolicy, { variableString })
+  }
 
   const fileRefEntry = {
     filePath: fullFilePath,

package/src/resolvers/valueFromGit.js

@@ -114,6 +114,32 @@ const GIT_KEYS = {
 }
 
 function createResolver(cwd) {
+  let gitRepo
+  const gitResultCache = new Map()
+
+  function isCurrentGitRepo() {
+    if (typeof gitRepo === 'undefined') {
+      gitRepo = isGitRepo(cwd)
+    }
+    return gitRepo
+  }
+
+  function cachedSafeGit(key, cmdFn) {
+    if (!gitResultCache.has(key)) {
+      gitResultCache.set(key, _safeGit(cmdFn))
+    }
+    return gitResultCache.get(key)
+  }
+
+  function gitExec(args) {
+    const key = `git:${JSON.stringify(args)}`
+    return cachedSafeGit(key, () => _execFile('git', args))
+  }
+
+  function gitRemote(name = 'origin') {
+    return cachedSafeGit(`remote:${name}`, () => getGitRemote(name))
+  }
+
   async function _getValueFromGit(variableString) {
     const variable = variableString.split(`${GIT_PREFIX}:`)[1]
     let value = null
@@ -123,14 +149,14 @@ function createResolver(cwd) {
     // undefined. This lets fallbacks like `${git:branch, "main"}` work, and
     // when there's no fallback the outer resolver throws a clear "Unable to
     // resolve config variable" error pointing at the config path.
-    if (!isGitRepo(cwd)) {
+    if (!isCurrentGitRepo()) {
       return undefined
     }
 
     if (variable.match(/^remote/i)) {
       const hasParams = functionRegex.exec(variableString)
       const remoteName = (hasParams && hasParams[2]) ? formatFunctionArgs(hasParams[2]) : 'origin'
-      return _safeGit(() => getGitRemote(remoteName))
+      return gitRemote(remoteName)
     }
 
     const normalizedVar = (variable || '').toLowerCase()
@@ -152,7 +178,7 @@ function createResolver(cwd) {
       case 'repository':
       case 'reposlug':
       case 'repo-slug': {
-        const urla = await _safeGit(() => getGitRemote())
+        const urla = await gitRemote()
         if (!urla) return undefined
         const parseda = GitUrlParse(urla)
         value = parseda.full_name
@@ -162,7 +188,7 @@ function createResolver(cwd) {
       case GIT_KEYS.name:
       case 'reponame': // repoName
       case 'repo-name': {
-        const toplevel = await _safeGit(() => _execFile('git', ['rev-parse', '--show-toplevel']))
+        const toplevel = await gitExec(['rev-parse', '--show-toplevel'])
         if (!toplevel) return undefined
         value = path.basename(toplevel)
         break
@@ -173,7 +199,7 @@ function createResolver(cwd) {
       case 'organization':
       case 'repoowner': // repoOwner
       case 'repo-owner': {
-        const url = await _safeGit(() => getGitRemote())
+        const url = await gitRemote()
         if (!url) return undefined
         const parsed = GitUrlParse(url)
         value = parsed.organization || parsed.owner
@@ -185,12 +211,12 @@ function createResolver(cwd) {
       case 'dirpath': // dirPath
       case 'dir-path':
       case 'dir_path': {
-        const gitBasePath = await _safeGit(() => _execFile('git', ['rev-parse', '--show-toplevel']))
+        const gitBasePath = await gitExec(['rev-parse', '--show-toplevel'])
         if (!gitBasePath) return undefined
         if (cwd) {
           const subPath = cwd.replace(gitBasePath, '')
-          const branch = await _safeGit(() => _execFile('git', ['rev-parse', '--abbrev-ref', 'HEAD']))
-          const url = await _safeGit(() => getGitRemote())
+          const branch = await gitExec(['rev-parse', '--abbrev-ref', 'HEAD'])
+          const url = await gitRemote()
           if (!url) return undefined
           value = (subPath && branch) ? `${url}/tree/${branch}${subPath}` : url
         }
@@ -200,12 +226,12 @@ function createResolver(cwd) {
       case GIT_KEYS.url:
       case 'repourl': // repoUrl
       case 'repo-url':
-        value = await _safeGit(() => getGitRemote())
+        value = await gitRemote()
         break
       // Current commit sha
       case 'sha':
       case 'sha1':
-        value = await _safeGit(() => _execFile('git', ['rev-parse', '--short', 'HEAD']))
+        value = await gitExec(['rev-parse', '--short', 'HEAD'])
         break
       // Current commit full sha
       case GIT_KEYS.commit:
@@ -213,7 +239,7 @@ function createResolver(cwd) {
       case 'commit-sha':
       case 'commithash':
       case 'commit-hash':
-        value = await _safeGit(() => _execFile('git', ['rev-parse', 'HEAD']))
+        value = await gitExec(['rev-parse', 'HEAD'])
         break
       // Branches
       case GIT_KEYS.branch:
@@ -221,7 +247,7 @@ function createResolver(cwd) {
       case 'branch-name':
       case 'currentbranch': // currentBranch
       case 'current-branch':
-        value = await _safeGit(() => _execFile('git', ['rev-parse', '--abbrev-ref', 'HEAD']))
+        value = await gitExec(['rev-parse', '--abbrev-ref', 'HEAD'])
         break
       // Commit msg
       case GIT_KEYS.message:
@@ -230,26 +256,26 @@ function createResolver(cwd) {
       case 'commit-message':
       case 'commitmsg': // commitMsg
       case 'commit-msg':
-        value = await _safeGit(() => _execFile('git', ['log', '-1', '--pretty=%B']))
+        value = await gitExec(['log', '-1', '--pretty=%B'])
         break
       // Git tags
       case GIT_KEYS.tag:
       case 'describe':
-        value = await _safeGit(() => _execFile('git', ['describe', '--always']))
+        value = await gitExec(['describe', '--always'])
         break
       // Git tags
       case 'describeLight':
       case 'describelight':
       case 'describe-light':
-        value = await _safeGit(() => _execFile('git', ['describe', '--always', '--tags']))
+        value = await gitExec(['describe', '--always', '--tags'])
         break
       // Is branch dirty
       case 'isDirty':
       case 'isdirty':
       case 'is-dirty': {
-        const writeTree = await _safeGit(() => _execFile('git', ['write-tree']))
+        const writeTree = await gitExec(['write-tree'])
         if (!writeTree) return undefined
-        const changes = await _safeGit(() => _execFile('git', ['diff-index', writeTree.trim(), '--']))
+        const changes = await gitExec(['diff-index', writeTree.trim(), '--'])
         if (changes === undefined) return undefined
         value = `${changes.length > 0}`
         break

package/src/resolvers/valueFromOptions.js

@@ -1,6 +1,6 @@
 // Resolves values from CLI option flags
-// Matches ${opt:FLAG_NAME} syntax with optional fallback values
-const optRefSyntax = RegExp(/^opt:/g)
+// Matches ${opt:FLAG_NAME} and ${option:FLAG_NAME} syntax with optional fallback values
+const optRefSyntax = RegExp(/^(?:opt|option):/g)
 
 function getValueFromOptions(variableString, options) {
   const requestedOption = variableString.split(':')[1]
@@ -12,8 +12,9 @@ module.exports = {
   type: 'options',
   source: 'user',
   prefix: 'opt',
-  syntax: '${opt:flagName}',
-  description: 'Resolves CLI option flags. Examples: ${opt:stage}, ${opt:other, "fallbackValue"}',
+  prefixes: ['opt', 'option'],
+  syntax: '${option:flagName}',
+  description: 'Resolves CLI option flags. Examples: ${option:stage}, ${opt:stage}, ${option:other, "fallbackValue"}',
   match: optRefSyntax,
   resolver: getValueFromOptions
 }

package/src/utils/filters/filterArgs.js

@@ -0,0 +1,57 @@
+const MARKER = '__CONFIGORAMA_FILTER_ARG__'
+
+class ResolvedFilterArg {
+  constructor(value) {
+    this.value = value
+    this.__resolvedFilterArg = true
+  }
+
+  toString() {
+    return String(this.value)
+  }
+
+  valueOf() {
+    return this.value
+  }
+}
+
+function encodeBase64Url(value) {
+  return Buffer.from(value).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function decodeBase64Url(value) {
+  let base64 = value.replace(/-/g, '+').replace(/_/g, '/')
+  while (base64.length % 4) base64 += '='
+  return Buffer.from(base64, 'base64').toString('utf8')
+}
+
+function encodeFilterArg(value) {
+  return `${MARKER}:${encodeBase64Url(JSON.stringify(value))}`
+}
+
+function isEncodedFilterArg(value) {
+  return typeof value === 'string' && value.startsWith(`${MARKER}:`)
+}
+
+function decodeFilterArg(value) {
+  if (!isEncodedFilterArg(value)) return value
+  const encoded = value.slice(MARKER.length + 1)
+  return new ResolvedFilterArg(JSON.parse(decodeBase64Url(encoded)))
+}
+
+function isResolvedFilterArg(value) {
+  return Boolean(value && value.__resolvedFilterArg)
+}
+
+function unwrapFilterArg(value) {
+  return isResolvedFilterArg(value) ? value.value : value
+}
+
+module.exports = {
+  ResolvedFilterArg,
+  decodeFilterArg,
+  encodeFilterArg,
+  isEncodedFilterArg,
+  isResolvedFilterArg,
+  unwrapFilterArg,
+}

package/src/utils/filters/oneOf.js

@@ -0,0 +1,77 @@
+const { splitCsv } = require('../strings/splitCsv')
+const { trimSurroundingQuotes } = require('../strings/quoteUtils')
+const { isResolvedFilterArg, unwrapFilterArg } = require('./filterArgs')
+
+function isRuntimeContextArg(value) {
+  return typeof value === 'string' && value.startsWith('from ')
+}
+
+function stripRuntimeContext(args) {
+  if (!args.length) return args
+  const last = args[args.length - 1]
+  return isRuntimeContextArg(last) ? args.slice(0, -1) : args
+}
+
+function hasDynamicArgument(value) {
+  return typeof value === 'string' && value.includes('${')
+}
+
+function parseOneOfLiteral(rawValue) {
+  const trimmed = String(rawValue).trim()
+  const unquoted = trimSurroundingQuotes(trimmed, false)
+  if (unquoted !== trimmed) return unquoted
+  if (/^-?(?:\d+|\d*\.\d+)(?:e[+-]?\d+)?$/i.test(trimmed)) return Number(trimmed)
+  return trimmed
+}
+
+function parseOneOfFilter(filter) {
+  if (typeof filter !== 'string') return null
+  const match = filter.match(/^oneOf\(([\s\S]*)\)$/)
+  if (!match) return null
+
+  const args = splitCsv(match[1], ',', { protectVariables: true })
+    .filter(arg => arg !== '')
+
+  if (args.some(hasDynamicArgument)) {
+    return {
+      dynamic: true,
+      allowedValues: null,
+    }
+  }
+
+  return {
+    dynamic: false,
+    allowedValues: args.map(arg => String(parseOneOfLiteral(arg))),
+  }
+}
+
+function validateOneOf(value, ...rawArgs) {
+  const args = stripRuntimeContext(rawArgs)
+  if (!args.length) {
+    throw new Error('Configorama Error: oneOf() requires at least one allowed value')
+  }
+  if (args.some(hasDynamicArgument)) {
+    throw new Error('Configorama Error: oneOf(${...}) dynamic arguments are not supported yet')
+  }
+
+  const hasResolvedFilterArg = args.some(isResolvedFilterArg)
+  const unwrappedArgs = args.map(unwrapFilterArg)
+  if (hasResolvedFilterArg) {
+    if (unwrappedArgs.length !== 1 || !Array.isArray(unwrappedArgs[0])) {
+      throw new Error('Configorama Error: oneOf(${...}) must resolve to an array')
+    }
+  }
+
+  const allowed = hasResolvedFilterArg ? unwrappedArgs[0] : unwrappedArgs
+  const allowedValues = allowed.map(String)
+  if (!allowedValues.some(allowed => allowed === String(value))) {
+    throw new Error(`Configorama Error: Value "${value}" is not oneOf(${allowedValues.join(', ')})`)
+  }
+  return value
+}
+
+module.exports = {
+  parseOneOfFilter,
+  parseOneOfLiteral,
+  validateOneOf,
+}