configorama 1.0.2 → 1.2.1

package/plugins/onepassword/normalize.js

@@ -0,0 +1,157 @@
+/* Normalizes 1Password references into canonical secretRef/item/privateLink forms
+   Validates aliases, parses private item links, rejects public share links */
+
+const ALIAS_PATTERN = /^[A-Za-z0-9_]+$/
+// 1Password item and vault IDs are 26-character lowercase base32 strings.
+const ITEM_ID_PATTERN = /^[a-z0-9]{26}$/
+const PRIVATE_LINK_PREFIXES = ['https://start.1password.com/open/i', 'onepassword://open/i']
+
+/**
+ * Whether a string has the shape of a 1Password item ID (26-char base32).
+ * Used to let colon syntax accept a bare item ID where an alias would go.
+ * @param {string} value - Candidate string
+ * @returns {boolean} True when it looks like an item ID
+ */
+function isItemId(value) {
+  return ITEM_ID_PATTERN.test(value)
+}
+
+/**
+ * Validate an alias name from the refs config.
+ * Dots are reserved as the key path separator so they cannot appear in aliases.
+ * @param {string} alias - Alias name to validate
+ */
+function validateAliasName(alias) {
+  if (!ALIAS_PATTERN.test(alias)) {
+    throw new Error(`Invalid 1Password alias "${alias}". Aliases may contain only letters, numbers, and underscores.`)
+  }
+}
+
+/**
+ * Check whether a string is a private item link.
+ * @param {string} value - Candidate string
+ * @returns {boolean} True when the string is a private item link
+ */
+function isPrivateLink(value) {
+  return PRIVATE_LINK_PREFIXES.some((prefix) => value.startsWith(prefix))
+}
+
+/**
+ * Recognize abbreviated private-link forms where the scheme, host, and/or
+ * path have been stripped, leaving the query params (e.g. "open/i?...&i=ID",
+ * or a bare "v=VAULT&i=ID"). Requires an "i=" param plus a 1Password marker
+ * or a pure query string, so ordinary item names and unrelated URLs are not
+ * misread as links.
+ * @param {string} value - Candidate string
+ * @returns {boolean} True when the string looks like private-link query params
+ */
+function looksLikeLinkParams(value) {
+  const query = value.includes('?') ? value.slice(value.indexOf('?') + 1) : value
+  if (!/(?:^|&)i=[^&]/.test(query)) return false
+  return /1password\.com/.test(value) || /(?:^|\/)open\/i/.test(value) || !value.includes('/')
+}
+
+/**
+ * Parse a "Copy Private Link" URL (or an abbreviated form) into item and
+ * vault IDs. The a (account) and h (host) params identify the account and are
+ * intentionally dropped; item + vault IDs are all op item get needs.
+ * @param {string} url - Private item link or its query params
+ * @returns {{kind: string, item: string, vault: string|undefined, warnings: Array<{code: string, message: string}>}} Normalized reference
+ */
+function parsePrivateLink(url) {
+  const query = url.includes('?') ? url.slice(url.indexOf('?') + 1) : url
+  const params = new URLSearchParams(query)
+  const item = params.get('i')
+  const vault = params.get('v')
+
+  if (!item) {
+    throw new Error('Invalid 1Password private link. Expected query parameter "i" with the item ID.')
+  }
+
+  const warnings = []
+  if (!vault) {
+    warnings.push({
+      level: 'warning',
+      code: 'op_private_link_missing_vault',
+      message: '1Password private link did not include a vault ID; service accounts and duplicate item names may require vault scoping.',
+    })
+  }
+
+  return { kind: 'privateLink', item, vault: vault || undefined, warnings }
+}
+
+/**
+ * Normalize a string or object ref value into a canonical reference.
+ * Accepted forms: op:// string, item name string, private link string,
+ * { item, vault, section, field }, { ref }, { url }.
+ * @param {string|object} value - Ref value from config or direct spec
+ * @returns {object} Normalized reference ({ kind: 'secretRef'|'item'|'privateLink', ... })
+ */
+function normalizeRefValue(value) {
+  if (typeof value === 'string') {
+    return normalizeStringRef(value)
+  }
+  if (value && typeof value === 'object') {
+    return normalizeObjectRef(value)
+  }
+  throw new Error(`Invalid 1Password reference. Expected a string or object, got ${typeof value}.`)
+}
+
+/**
+ * @param {string} value - String ref (secret ref, link, or item name)
+ * @returns {object} Normalized reference
+ */
+function normalizeStringRef(value) {
+  if (value.startsWith('op://')) {
+    return { kind: 'secretRef', ref: value }
+  }
+  // Public share links are rejected in any form (full URL or share token).
+  if (value.includes('share.1password.com') || /1password\.com\/s#/.test(value)) {
+    throw new Error('Public 1Password share links are not supported. Use Copy Private Link or an op:// secret reference.')
+  }
+  // Private links: full URL, onepassword://, or an abbreviated form carrying
+  // the query params (scheme/host/path stripped).
+  if (isPrivateLink(value) || looksLikeLinkParams(value)) {
+    return parsePrivateLink(value)
+  }
+  if (/^https?:\/\/|^onepassword:\/\//.test(value)) {
+    throw new Error('Unrecognized 1Password link. Use Copy Private Link or an op:// secret reference.')
+  }
+  return { kind: 'item', item: value, vault: undefined, section: undefined, field: undefined }
+}
+
+/**
+ * @param {object} value - Object ref ({ item }, { ref }, or { url })
+ * @returns {object} Normalized reference
+ */
+function normalizeObjectRef(value) {
+  const specifiers = ['item', 'ref', 'url'].filter((key) => value[key] !== undefined)
+  if (specifiers.length !== 1) {
+    throw new Error('Invalid 1Password reference. Object refs must specify exactly one of "item", "ref", or "url".')
+  }
+
+  if (value.ref !== undefined) {
+    return normalizeStringRef(value.ref)
+  }
+  if (value.url !== undefined) {
+    const normalized = normalizeStringRef(value.url)
+    if (normalized.kind !== 'privateLink') {
+      throw new Error('Invalid 1Password reference. "url" must be a private item link.')
+    }
+    return normalized
+  }
+
+  if (value.section !== undefined && value.field === undefined) {
+    throw new Error('Invalid 1Password reference. "section" is only meaningful together with "field".')
+  }
+
+  return {
+    kind: 'item',
+    item: value.item,
+    vault: value.vault,
+    section: value.section,
+    field: value.field,
+  }
+}
+
+module.exports = { validateAliasName, normalizeRefValue, parsePrivateLink, isPrivateLink, isItemId }

package/plugins/onepassword/op-cli.js

@@ -0,0 +1,117 @@
+/* Executes the 1Password CLI with execFile and sanitized error translation
+   Never logs stdout/stderr; never passes resolved secret values as arguments */
+const childProcess = require('child_process')
+
+const AUTH_ERROR_PATTERN = /sign ?in|session|authoriz|authenticat|not currently signed|locked|service account token/i
+const NOT_FOUND_PATTERN = /isn'?t an? (item|vault)|not found|no item|no vault|doesn'?t exist|more than one item/i
+
+/**
+ * Run the op binary with the given args.
+ * No `command -v op` preflight: translating ENOENT is the existence check.
+ * @param {string[]} args - CLI arguments
+ * @param {object} [options] - { execFile, opPath, account, configDir, subject }
+ * @returns {Promise<string>} stdout
+ */
+function runOp(args, options = {}) {
+  const execFile = options.execFile || childProcess.execFile
+  const binary = options.opPath || 'op'
+  const finalArgs = args.slice()
+  if (options.account) {
+    finalArgs.push('--account', options.account)
+  }
+  if (options.configDir) {
+    finalArgs.push('--config', options.configDir)
+  }
+
+  return new Promise((resolve, reject) => {
+    execFile(binary, finalArgs, { maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        return reject(translateError(err, stderr, options.subject))
+      }
+      resolve(stdout)
+    })
+  })
+}
+
+/**
+ * Translate op failures into sanitized, actionable errors.
+ * stderr is inspected for classification but never included in messages.
+ * @param {Error & {code?: string|number}} err - execFile error
+ * @param {string} stderr - Captured stderr (classification only)
+ * @param {string} [subject] - Item/ref identifier already present in user config
+ * @returns {Error} Sanitized error
+ */
+function translateError(err, stderr, subject) {
+  if (err.code === 'ENOENT') {
+    return new Error('1Password CLI "op" was not found on PATH. Install 1Password CLI or remove the op resolver.')
+  }
+  const detail = String(stderr || err.message || '')
+  if (AUTH_ERROR_PATTERN.test(detail)) {
+    return new Error('1Password CLI could not read the item. Run op signin, unlock 1Password app integration, or configure OP_SERVICE_ACCOUNT_TOKEN.')
+  }
+  if (NOT_FOUND_PATTERN.test(detail)) {
+    const what = subject ? `"${subject}"` : 'the requested item, vault, or field'
+    return new Error(`1Password item, vault, or field could not be found (${what}).`)
+  }
+  return new Error('1Password CLI command failed.')
+}
+
+/**
+ * Reject config-controlled values that would be parsed as an op flag.
+ * execFile takes no shell, so this is not command injection - but a
+ * leading "-" turns a positional/vault value into an option that changes
+ * op's behavior. Secret refs are exempt: they always start with "op://".
+ * @param {string} value - Value destined for the op argument list
+ * @param {string} label - Human label for the error message
+ */
+function assertNotFlag(value, label) {
+  if (typeof value === 'string' && value.startsWith('-')) {
+    throw new Error(`Invalid 1Password ${label} "${value}": ${label} cannot start with "-" (it would be read as an op flag). Use the item ID or an op:// secret reference.`)
+  }
+}
+
+/**
+ * Read a secret reference with op read.
+ * @param {string} ref - op://vault/item/field reference
+ * @param {object} [options] - { execFile, account, configDir }
+ * @returns {Promise<string>} Secret value
+ */
+function readSecretRef(ref, options = {}) {
+  return runOp(['read', '--no-newline', ref], {
+    execFile: options.execFile,
+    opPath: options.opPath,
+    account: options.account,
+    configDir: options.configDir,
+    subject: ref,
+  })
+}
+
+/**
+ * Fetch an item as JSON with op item get.
+ * --reveal is required to include concealed field values in the JSON.
+ * @param {string} spec - Item ID or item name
+ * @param {object} [options] - { execFile, account, configDir, vault }
+ * @returns {Promise<object>} Parsed item JSON
+ */
+async function getItem(spec, options = {}) {
+  assertNotFlag(spec, 'item')
+  const args = ['item', 'get', spec, '--format', 'json', '--reveal']
+  if (options.vault) {
+    assertNotFlag(options.vault, 'vault')
+    args.push('--vault', options.vault)
+  }
+  const stdout = await runOp(args, {
+    execFile: options.execFile,
+    opPath: options.opPath,
+    account: options.account,
+    configDir: options.configDir,
+    subject: spec,
+  })
+  try {
+    return JSON.parse(stdout)
+  } catch (err) {
+    throw new Error(`Could not parse 1Password CLI output as JSON for item "${spec}".`)
+  }
+}
+
+module.exports = { runOp, readSecretRef, getItem }

package/plugins/onepassword/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "configorama-onepassword",
+  "version": "0.1.0",
+  "description": "1Password variable source plugin for configorama",
+  "main": "index.js",
+  "scripts": {
+    "test": "node parser.test.js && node normalize.test.js && node op-cli.test.js && node fields.test.js && node index.test.js && node smoke.test.js"
+  },
+  "keywords": [
+    "configorama",
+    "1password",
+    "secrets"
+  ],
+  "license": "MIT"
+}

package/plugins/onepassword/parser.js

@@ -0,0 +1,70 @@
+/* Parses 1Password field text as INI/dotenv for key path reads
+   Raw field text is only parsed when a config reference asks for a key path */
+const ini = require('ini')
+
+/**
+ * Restore ini module coercions so secret values stay strings.
+ * The ini parser coerces true/false/null which corrupts literal
+ * secret text like FLAG=true.
+ * @param {*} value - Parsed ini node
+ * @returns {*} Node with primitives restored to strings
+ */
+function stringifyPrimitives(value) {
+  if (value === true) return 'true'
+  if (value === false) return 'false'
+  if (value === null) return 'null'
+  if (typeof value === 'object') {
+    const result = {}
+    for (const key of Object.keys(value)) {
+      result[key] = stringifyPrimitives(value[key])
+    }
+    return result
+  }
+  return value
+}
+
+/**
+ * Parse structured secret text.
+ * V1 supports INI/dotenv only. Future format detection order:
+ * 1. explicit format option on the ref
+ * 2. JSON if the trimmed value starts with { or [
+ * 3. YAML only with proof it is not confused with INI
+ * 4. INI fallback
+ * @param {string} value - Raw field text
+ * @param {object} [options] - Reserved for future format selection
+ * @returns {object} Parsed key/value structure
+ */
+function parseStructuredSecret(value, options = {}) {
+  let parsed
+  try {
+    parsed = ini.parse(value)
+  } catch (err) {
+    throw new Error(`Could not parse 1Password field "${options.fieldName || 'value'}" as INI/dotenv.`)
+  }
+  return stringifyPrimitives(parsed)
+}
+
+/**
+ * Read a dot-separated key path from a parsed structure.
+ * Error messages never include secret values.
+ * @param {object} parsed - Result of parseStructuredSecret
+ * @param {string} keyPath - Dot-separated path, e.g. "database.password"
+ * @param {string} fieldName - 1Password field name for error messages
+ * @returns {string} Selected value
+ */
+function getKeyPath(parsed, keyPath, fieldName) {
+  const segments = keyPath.split('.')
+  let current = parsed
+  for (const segment of segments) {
+    if (current === null || typeof current !== 'object' || !(segment in current)) {
+      throw new Error(`Key path "${keyPath}" was not found in 1Password field "${fieldName}".`)
+    }
+    current = current[segment]
+  }
+  if (typeof current === 'object') {
+    throw new Error(`Key path "${keyPath}" was not found in 1Password field "${fieldName}".`)
+  }
+  return current
+}
+
+module.exports = { parseStructuredSecret, getKeyPath }

package/plugins/onepassword/sync-factory.js

@@ -0,0 +1,15 @@
+/* Factory entry for configorama.sync() workers
+   Rebuilds the 1Password resolver from JSON-serializable options inside the sync worker */
+const createOnePasswordResolver = require('./index')
+
+/**
+ * @param {object} options - JSON-round-tripped syncOptions ({ refs, account, configDir, skipResolution })
+ * @returns {object} Variable source
+ */
+module.exports = function createSyncOnePasswordResolver(options = {}) {
+  if (options.hasInjectedExecFile) {
+    throw new Error('1Password resolver options are not serializable for sync usage. Remove the injected execFile or use the async API.')
+  }
+  const { hasInjectedExecFile, ...factoryOptions } = options
+  return createOnePasswordResolver(factoryOptions)
+}

package/src/errors.js

@@ -16,6 +16,9 @@ const ERROR_CODES = [
   { code: 'no_input_file', description: 'No config file was provided on the command line.' },
   { code: 'file_not_found', description: 'The provided config file path does not exist.' },
   { code: 'path_not_found', description: 'A jq-style extraction path matched nothing in the resolved config.' },
+  { code: 'invalid_env_key', description: 'A setup write target received a key that is not a valid dotenv name.' },
+  { code: 'target_file_exists', description: 'A setup write target already exists and neither --merge nor --force was passed.' },
+  { code: 'managed_block_invalid', description: 'A dotenv merge target has missing, duplicated, or out-of-order managed block markers.' },
   { code: 'configorama_error', description: 'Generic, unclassified configorama error.' },
 ]
 

package/src/index.js

@@ -4,6 +4,9 @@ const enrichMetadata = require('./utils/parsing/enrichMetadata')
 const { buildVariableSyntax } = require('./utils/variables/variableUtils')
 const { serializeRequirements } = require('./utils/requirements/serializeRequirements')
 const { buildConfigRequirements } = require('./utils/requirements/configRequirements')
+const { runSetup } = require('./utils/setup/setupEngine')
+const { writeDotenv } = require('./utils/setup/writeDotenv')
+const { writeAnswers } = require('./utils/setup/writeAnswers')
 const { buildIntrospection } = require('./utils/introspection/model')
 const { buildAuditReport } = require('./utils/introspection/audit')
 const { formatGraph } = require('./utils/introspection/graph')
@@ -142,6 +145,22 @@ module.exports.analyze = async (configPathOrObject, settings = {}) => {
   return analysis
 }
 
+/**
+ * Run the interactive setup wizard and return grouped answers without applying them
+ * @param {string|Object} configPathOrObject - Path to config file or raw config object
+ * @param {object} [settings] - Same settings as the main API, plus promptRenderer/streams
+ * @return {Promise<object>} { schemaVersion, configPath, requirements, answers, redactedAnswers }
+ */
+module.exports.setup = async (configPathOrObject, settings = {}) => {
+  return runSetup(configPathOrObject, settings, { analyze: module.exports.analyze })
+}
+
+/**
+ * Safe writers for persisting setup answers (0600, atomic, overwrite-guarded)
+ */
+module.exports.writeDotenv = writeDotenv
+module.exports.writeAnswers = writeAnswers
+
 module.exports.introspect = async (configPathOrObject, settings = {}) => {
   const analysis = await module.exports.analyze(configPathOrObject, {
     ...settings,
@@ -163,7 +182,14 @@ module.exports.audit = async (configPathOrObject, settings = {}) => {
   const requirements = buildConfigRequirements(analysis)
   const introspection = buildIntrospection(analysis, { requirements })
   const customResolvers = Array.isArray(settings.variableSources)
-    ? settings.variableSources.map(source => source.type).filter(Boolean)
+    ? settings.variableSources
+      .filter(source => source.type)
+      .map(source => ({
+        type: source.type,
+        sensitive: source.sensitive,
+        risk: source.risk,
+        description: source.description,
+      }))
     : []
   const originalConfig = analysis.originalConfig || {}
   return buildAuditReport(introspection, {

package/src/main.js

@@ -92,6 +92,7 @@ const { mergeByKeys } = require('./utils/parsing/mergeByKeys')
 const { arrayToJsonPath } = require('./utils/parsing/arrayToJsonPath')
 /* Utils - paths */
 const { findLineByPath } = require('./utils/paths/findLineForKey')
+const { configFileType } = require('./utils/paths/fileType')
 const { normalizeIgnorePaths, compileIgnorePaths, shouldIgnorePath } = require('./utils/paths/ignorePaths')
 /* Utils - regex */
 const { combineRegexes, funcRegex, fileRefSyntax, textRefSyntax } = require('./utils/regex')
@@ -109,9 +110,8 @@ const { validateOneOf } = require('./utils/filters/oneOf')
 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')
+const { runSetup } = require('./utils/setup/setupEngine')
+const { applyAnswers } = require('./utils/setup/applyAnswers')
 /* Display */
 const { displayNoVariablesFound, displayVariableDetails, displayUniqueVariables, displayConfigurableVariables } = require('./display')
 /* Metadata */
@@ -175,7 +175,6 @@ const functionPrefixPattern = /^> function /
 
 let DEBUG = process.argv.includes('--debug') ? true : false
 let VERBOSE = process.argv.includes('--verbose') ? true : false
-let SETUP_MODE = process.argv.includes('--setup') ? true : false
 // DEBUG = true
 let DEBUG_TYPE = false
 
@@ -187,8 +186,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
+    // Setup wizard is explicit opt-in: the CLI translates --setup/`setup` into options.setup
+    this.setupMode = 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
@@ -939,34 +938,25 @@ class Configorama {
       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)
+        const setupResult = await runSetup(this.configFilePath || this.config, this.settings, {
+          analysis: Object.assign({ originalConfig: this.originalConfig }, enrich),
+        })
+        this.setupRequirements = setupResult.requirements
+
+        // Summary shows only answered groups, sensitive values redacted
+        const displayInputs = {}
+        for (const [group, values] of Object.entries(setupResult.redactedAnswers)) {
+          if (Object.keys(values).length > 0) {
+            displayInputs[group] = values
+          }
+        }
 
         logHeader('User Inputs Summary')
         console.log()
         console.log(JSON.stringify(displayInputs, null, 2))
 
-        // TODO set values
-
-        // Apply user inputs to options and environment
-        if (userInputs.options) {
-          Object.assign(this.options, userInputs.options)
-        }
-        if (userInputs.env) {
-          Object.assign(process.env, userInputs.env)
-        }
-
-        if (userInputs.self) {
-          Object.assign(this.config, userInputs.self)
-        }
-
-        if (userInputs.dotProp) {
-          for (const [key, value] of Object.entries(userInputs.dotProp)) {
-            dotProp.set(this.config, key, value)
-          }
-        }
+        // Apply user inputs to options, environment, and config
+        applyAnswers({ options: this.options, env: process.env, config: this.config }, setupResult.answers)
 
         console.log()
         logHeader('Resolving Configuration')
@@ -2574,8 +2564,8 @@ Missing Value ${missingValue} - ${matchedString}
           if (valueCount.length === 1 && noNestedVars) {
             let lineInfo = ''
             if (this.originalString && this.configFilePath && valueObject.path) {
-              const ext = path.extname(this.configFilePath)
-              if (ext === '.yml' || ext === '.yaml' || ext === '.json') {
+              const ext = configFileType(this.configFilePath)
+              if (ext === '.yml' || ext === '.yaml' || ext === '.json' || ext === '.env') {
                 const rawLines = this.originalString.split('\n')
                 const lineNum = findLineByPath(arrayToJsonPath(valueObject.path), rawLines, ext)
                 if (lineNum) lineInfo = ` at line ${lineNum},`
@@ -3049,7 +3039,9 @@ Missing Value ${missingValue} - ${matchedString}
   // ###############
   initialCall(func) {
     this.deep = []
-    this.tracker.start()
+    // Progress reporting is a debug-only aid; the tracker still coordinates
+    // promises and detects cycles regardless.
+    this.tracker.start(DEBUG)
     return func().finally(() => {
       this.tracker.stop()
       this.deep = []

package/src/parsers/dotenv.js

@@ -0,0 +1,13 @@
+// Parses .env file contents into a flat key/value object
+// Values keep their raw text so configorama can resolve ${...} references in them
+const dotenv = require('dotenv')
+
+/**
+ * @param {string} contents - Raw .env file text
+ * @returns {Object} Flat map of KEY -> raw string value
+ */
+function parse(contents) {
+  return dotenv.parse(contents)
+}
+
+module.exports = { parse }

package/src/resolvers/valueFromFile.js

@@ -266,7 +266,8 @@ Default fallback value will be used if provided.
 
 ${JSON.stringify(options.context, null, 2)}`,
       })
-      console.log(errorMsg)
+      // Diagnostic goes to stderr so it never pollutes resolved-config stdout
+      console.error(errorMsg)
     }
     // TODO maybe reject. YAML does not allow for null/undefined values
     // return Promise.reject(new Error(errorMsg))

package/src/sync.js

@@ -9,6 +9,21 @@ const enrichMetadata = require('./utils/parsing/enrichMetadata')
  */
 module.exports = function configoramaSync(variableSources = []) {
   const customVariableSources = variableSources.map((varSrc) => {
+    /* Plugin factories: match/resolver do not survive the JSON trip through
+       sync-rpc, so plugins carry a syncFactory path + JSON syncOptions and
+       the real source is rebuilt here inside the worker process */
+    if (varSrc.syncFactory) {
+      const factoryPath = getFullPath(varSrc.syncFactory)
+      if (!fs.existsSync(factoryPath)) {
+        throw new Error(`Sync factory missing. Can't find ${factoryPath}`)
+      }
+      const createSource = require(factoryPath)
+      if (typeof createSource !== 'function') {
+        throw new Error(`Sync factory must export a function. Check ${factoryPath}`)
+      }
+      return createSource(varSrc.syncOptions || {})
+    }
+
     if (!varSrc.match || typeof varSrc.match !== 'string') {
       throw new Error('Variable source must be string for .sync usage')
     }
@@ -67,6 +82,18 @@ module.exports = function configoramaSync(variableSources = []) {
         instance.variableTypes
       )
 
+      /* Collect custom metadata from worker-side sources, mirroring the
+         collectMetadata loop the async API runs in src/index.js */
+      for (const source of customVariableSources) {
+        if (typeof source.collectMetadata === 'function') {
+          const customData = source.collectMetadata()
+          if (customData !== undefined && customData !== null) {
+            const metadataKey = source.metadataKey || `${source.type}References`
+            enrichedMetadata[metadataKey] = customData
+          }
+        }
+      }
+
       return {
         variableSyntax: instance.variableSyntax,
         variableTypes: instance.variableTypes,

package/src/utils/PromiseTracker.js

@@ -13,15 +13,21 @@ class PromiseTracker {
     this.startTime = Date.now()
     this.cursor = 0
   }
-  start() {
+  start(enableProgress = false) {
     this.reset()
-    this.interval = setInterval(this.report.bind(this), 2500)
+    // The tracker's job is cycle detection and promise coordination; the
+    // periodic progress report is a debug-only aid, off unless requested.
+    if (enableProgress) {
+      this.interval = setInterval(this.report.bind(this), 2500)
+    }
   }
   report() {
     const delta = Date.now() - this.startTime
     const pending = this.getPending()
     const dots = dotDotDot(this.cursor++, 100, '...')
-    console.log([
+    // Diagnostic progress goes to stderr so it never pollutes stdout (resolved
+    // config output, or `configx --export` lines consumed by eval).
+    console.error([
       `Fetching Async values${dots}`,
     ].concat(
       pending.map((promise) => `- ${promise.waitList}`)
@@ -40,7 +46,8 @@ class PromiseTracker {
     /**/
   }
   stop() {
-    clearInterval(this.interval)
+    if (this.interval) clearInterval(this.interval)
+    this.interval = null
     this.reset()
   }
   add(variable, promise, specifier, hasFilter, promiseKey) {