configorama 1.0.2 → 1.2.1

package/src/utils/PromiseTracker.test.js

@@ -0,0 +1,48 @@
+/* Tests that resolution progress output goes to stderr, not stdout */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const PromiseTracker = require('./PromiseTracker')
+
+test('start() does not enable progress logging by default', () => {
+  const tracker = new PromiseTracker()
+  tracker.start()
+  const hasInterval = !!tracker.interval
+  tracker.stop()
+  assert.is(hasInterval, false, 'no interval timer unless progress is requested')
+})
+
+test('start(true) enables the progress interval; stop() clears it', () => {
+  const tracker = new PromiseTracker()
+  tracker.start(true)
+  assert.ok(tracker.interval, 'interval set when progress requested')
+  tracker.stop()
+  assert.is(tracker.interval, null, 'interval cleared on stop')
+})
+
+test('report() writes progress to stderr, not stdout', () => {
+  const tracker = new PromiseTracker()
+  const pending = Promise.resolve()
+  tracker.add('${op(a?x=1&y=2)}', pending, '${op(a?x=1&y=2)}')
+  // add() attaches a .then that flips state to resolved on next tick; force pending
+  tracker.promiseList[0].state = 'pending'
+
+  const outLines = []
+  const errLines = []
+  const origLog = console.log
+  const origErr = console.error
+  console.log = (...args) => outLines.push(args.join(' '))
+  console.error = (...args) => errLines.push(args.join(' '))
+  try {
+    tracker.report()
+  } finally {
+    console.log = origLog
+    console.error = origErr
+  }
+
+  assert.is(outLines.length, 0, 'nothing on stdout')
+  assert.ok(errLines.some((line) => line.includes('Fetching Async values')), 'progress on stderr')
+  // the pending variable (with & in it) must not leak to stdout
+  assert.ok(outLines.every((line) => !line.includes('&')))
+})
+
+test.run()

package/src/utils/introspection/audit.js

@@ -41,15 +41,11 @@ function buildAuditReport(introspection, options = {}) {
   }
 
   if (options.customResolvers && options.customResolvers.length) {
-    for (const resolver of options.customResolvers.slice().sort()) {
-      findings.push({
-        id: `customResolver:${resolver}`,
-        severity: 'high',
-        risk: 'custom_extension',
-        kind: 'source',
-        variableType: resolver,
-        message: `Custom resolver "${resolver}" can execute user-provided code.`,
-      })
+    const sorted = options.customResolvers.slice().sort((a, b) => {
+      return String(a.type || a).localeCompare(String(b.type || b))
+    })
+    for (const resolver of sorted) {
+      findings.push(customResolverFinding(resolver))
     }
   }
 
@@ -70,6 +66,40 @@ function buildAuditReport(introspection, options = {}) {
   }
 }
 
+/**
+ * Build the audit finding for one custom resolver.
+ * Resolvers that self-describe as sensitive/risky get a specific finding
+ * instead of the generic custom_extension one - never both.
+ * @param {string|{type: string, sensitive?: boolean, risk?: string, description?: string}} resolver
+ * @returns {object} Audit finding
+ */
+function customResolverFinding(resolver) {
+  const source = typeof resolver === 'string' ? { type: resolver } : resolver
+  const { type, sensitive, risk, description } = source
+
+  if (sensitive === true || risk) {
+    const finding = {
+      id: `customResolver:${type}`,
+      severity: 'high',
+      risk: risk || 'custom_extension',
+      kind: 'source',
+      variableType: type,
+      message: `Custom resolver "${type}" reads secret values.${description ? ` ${description}.` : ''}`,
+    }
+    if (sensitive === true) finding.sensitive = true
+    return finding
+  }
+
+  return {
+    id: `customResolver:${type}`,
+    severity: 'high',
+    risk: 'custom_extension',
+    kind: 'source',
+    variableType: type,
+    message: `Custom resolver "${type}" can execute user-provided code.`,
+  }
+}
+
 function messageForNode(node) {
   if (node.risk === 'executable_code') return 'Reference may execute JavaScript or TypeScript.'
   if (node.risk === 'process_spawn') return 'Reference may spawn a git process.'

package/src/utils/parsing/detectFormat.js

@@ -0,0 +1,70 @@
+// Detects a config file's format from raw content when its name/extension is
+// ambiguous. Returns a file-extension string for the parser dispatch in parse.js.
+// Best-effort heuristic — an explicit, recognized extension always wins over this.
+
+/**
+ * Whether every meaningful line is a flat KEY=VALUE assignment (dotenv shape).
+ * Deliberately variable-syntax-agnostic: it inspects line structure, not the
+ * variable delimiters, so it works whether a config uses ${...}, $[...], or a
+ * custom syntax. Blank lines and #/; comments are ignored.
+ * @param {string} text - Trimmed file contents
+ * @returns {boolean} True for flat key=value content with no YAML/TOML structure
+ */
+function isFlatKeyValue(text) {
+  const lines = text.split('\n')
+  let assignments = 0
+  for (const raw of lines) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue
+    if (/^(?:export\s+)?[A-Za-z_][A-Za-z0-9_.-]*\s*=/.test(line)) {
+      assignments++
+      continue
+    }
+    // A non-blank, non-comment line that isn't an assignment (e.g. a YAML
+    // mapping, a TOML section, or freeform text) — not a flat env file.
+    return false
+  }
+  return assignments > 0
+}
+
+/**
+ * Detect config format from file contents when the extension is missing or
+ * unrecognized.
+ * @param {string} contents - Raw file contents
+ * @returns {string} Detected file extension (e.g. '.json', '.yml', '.toml', '.env')
+ */
+function detectFormat(contents) {
+  const trimmed = contents.trimStart()
+
+  // JSON object: starts with {
+  if (trimmed[0] === '{') return '.json'
+
+  // TOML section headers must be checked before JSON array (both start with [)
+  // TOML: [section.subsection] (dots distinguish from INI)
+  if (/^\[[\w-]+\.[\w.-]+\]/.test(trimmed)) return '.toml'
+  // TOML: array-of-tables [[section]]
+  if (/^\[\[[\w.-]+\]\]/.test(trimmed)) return '.toml'
+
+  // JSON array: starts with [ followed by non-word char (quotes, numbers, braces, whitespace)
+  if (trimmed[0] === '[') return '.json'
+
+  // TOML: multi-line strings
+  if (trimmed.startsWith('"""')) return '.toml'
+
+  // YAML: starts with document marker
+  if (trimmed.startsWith('---')) return '.yml'
+
+  // HCL: terraform keywords
+  if (/^(resource|variable|locals|provider|data|module|output|terraform)\s/.test(trimmed)) return '.tf'
+
+  // Flat KEY=VALUE content (env-file shape) -> dotenv parser. dotenv is lossless
+  // for string values, which is what configorama resolves ${...} into. TOML
+  // errors on unquoted values; ini truncates values at ';' (breaks connection
+  // strings) and mangles 'export' prefixes.
+  if (isFlatKeyValue(trimmed)) return '.env'
+
+  // Default: YAML (most permissive parser)
+  return '.yml'
+}
+
+module.exports = { detectFormat, isFlatKeyValue }

package/src/utils/parsing/detectFormat.test.js

@@ -0,0 +1,68 @@
+/* Tests for content-based config format detection */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { detectFormat, isFlatKeyValue } = require('./detectFormat')
+
+/* JSON */
+test('detects JSON object and array', () => {
+  assert.is(detectFormat('{\n  "a": 1\n}'), '.json')
+  assert.is(detectFormat('[\n  {"a": 1}\n]'), '.json')
+})
+
+/* TOML — structural markers win */
+test('detects TOML by section headers and leading multiline string', () => {
+  assert.is(detectFormat('[server.settings]\nname = "test"\nport = 3000'), '.toml')
+  assert.is(detectFormat('[[items]]\nname = "a"'), '.toml')
+  assert.is(detectFormat('"""\nmulti\n"""'), '.toml')
+})
+
+/* YAML */
+test('detects YAML by document marker and mappings', () => {
+  assert.is(detectFormat('---\nname: test'), '.yml')
+  assert.is(detectFormat('name: test\nport: 3000'), '.yml')
+})
+
+test('YAML with template values still detects as YAML', () => {
+  assert.is(detectFormat("name: ${env:APP_NAME, 'x'}\nport: 3000"), '.yml')
+})
+
+/* HCL */
+test('detects terraform/HCL by keyword', () => {
+  assert.is(detectFormat('variable "region" {\n  default = "us-east-1"\n}'), '.tf')
+})
+
+/* dotenv — flat key=value shape */
+test('detects flat key=value (no space) as dotenv', () => {
+  assert.is(detectFormat('FOO=bar\nBAZ=qux'), '.env')
+})
+
+test('detects key=value with template values as dotenv (syntax-agnostic)', () => {
+  assert.is(detectFormat('stage=${option:stage}\nDB=${op:x}'), '.env')
+  // custom variable syntax must not change detection
+  assert.is(detectFormat('stage=$[option:stage]\nDB=$[op:x]'), '.env')
+})
+
+test('detects dotenv with comments and export prefixes', () => {
+  assert.is(detectFormat('# comment\nexport TOKEN=abc\nURL=postgres://h/db;sslmode=require'), '.env')
+})
+
+test('a single non-assignment line disqualifies dotenv detection', () => {
+  // has a YAML mapping mixed in -> not flat key=value -> YAML default
+  assert.is(detectFormat('FOO=bar\nname: test'), '.yml')
+})
+
+test('empty or comment-only content is not dotenv', () => {
+  assert.is(detectFormat('# just a comment\n'), '.yml')
+  assert.is(detectFormat(''), '.yml')
+})
+
+/* isFlatKeyValue unit */
+test('isFlatKeyValue recognizes assignment lines only', () => {
+  assert.is(isFlatKeyValue('A=1\nB=2'), true)
+  assert.is(isFlatKeyValue('export A=1\n# c\nB=2'), true)
+  assert.is(isFlatKeyValue('A=1\nplain text line'), false)
+  assert.is(isFlatKeyValue('name: value'), false)
+  assert.is(isFlatKeyValue(''), false)
+})
+
+test.run()

package/src/utils/parsing/parse.js

@@ -4,8 +4,11 @@ const path = require('path')
 const YAML = require('../../parsers/yaml')
 const TOML = require('../../parsers/toml')
 const INI = require('../../parsers/ini')
+const DOTENV = require('../../parsers/dotenv')
 const JSON5 = require('../../parsers/json5')
 const HCL = require('../../parsers/hcl')
+const { isEnvFile } = require('../paths/fileType')
+const { detectFormat } = require('./detectFormat')
 const { executeTypeScriptFileSync } = require('../../parsers/typescript')
 const { executeESMFileSync } = require('../../parsers/esm')
 const cloudFormationSchema = require('./cloudformationSchema')
@@ -21,41 +24,6 @@ const KNOWN_EXTENSIONS = new Set([
   '.md', '.mdx', '.markdown', '.mdown', '.mkdn', '.mkd', '.mdwn', '.markdn', '.mdtxt', '.mdtext'
 ])
 
-/**
- * Detect config format from file contents when extension is missing
- * @param {string} contents - Raw file contents
- * @returns {string} Detected file extension (e.g. '.json', '.yml', '.toml')
- */
-function detectFormat(contents) {
-  const trimmed = contents.trimStart()
-
-  // JSON object: starts with {
-  if (trimmed[0] === '{') return '.json'
-
-  // TOML section headers must be checked before JSON array (both start with [)
-  // TOML: [section.subsection] (dots distinguish from INI)
-  if (/^\[[\w-]+\.[\w.-]+\]/.test(trimmed)) return '.toml'
-  // TOML: array-of-tables [[section]]
-  if (/^\[\[[\w.-]+\]\]/.test(trimmed)) return '.toml'
-
-  // JSON array: starts with [ followed by non-word char (quotes, numbers, braces, whitespace)
-  if (trimmed[0] === '[') return '.json'
-
-  // TOML: multi-line strings
-  if (trimmed.startsWith('"""')) return '.toml'
-  // TOML: key = value
-  if (/^\w[\w.-]*\s*=\s/m.test(trimmed)) return '.toml'
-
-  // YAML: starts with document marker
-  if (trimmed.startsWith('---')) return '.yml'
-
-  // HCL: terraform keywords
-  if (/^(resource|variable|locals|provider|data|module|output|terraform)\s/.test(trimmed)) return '.tf'
-
-  // Default: YAML (most permissive parser)
-  return '.yml'
-}
-
 /**
  * @typedef {Object} ParseOptions
  * @property {string} contents - Raw file contents to parse
@@ -72,8 +40,12 @@ function detectFormat(contents) {
 function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
   let fileType = path.extname(filePath)
 
-  // Content-based detection for extensionless or unrecognized files
-  if (!fileType || !KNOWN_EXTENSIONS.has(fileType.toLowerCase())) {
+  // Dotenv files have no extension (path.extname('.env') === ''), so detect
+  // them by name before falling back to content sniffing.
+  if (isEnvFile(filePath)) {
+    fileType = '.env'
+  } else if (!fileType || !KNOWN_EXTENSIONS.has(fileType.toLowerCase())) {
+    // Content-based detection for extensionless or unrecognized files
     fileType = detectFormat(contents)
   }
 
@@ -105,6 +77,8 @@ function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
     configObject = TOML.parse(contents)
   } else if (fileType.match(/\.(ini)/i)) {
     configObject = INI.parse(contents)
+  } else if (fileType === '.env') {
+    configObject = DOTENV.parse(contents)
   } else if (fileType.match(/\.(json|json5|jsonc)/i)) {
     configObject = JSON5.parse(contents)
   } else if (fileType.match(/\.(tf|hcl)$/i) || filePath.match(/\.tf\.json$/i)) {

package/src/utils/paths/fileType.js

@@ -0,0 +1,27 @@
+// Classifies config files by type, treating dotenv files as ".env"
+// so extension-less names like .env / .env.local / deploy.env resolve consistently
+const path = require('path')
+
+/**
+ * Whether a path is a dotenv file (.env, .env.local, deploy.env, ...).
+ * `path.extname('.env')` is '' (dotfile), so detection is by basename.
+ * @param {string} filePath - File path or name
+ * @returns {boolean} True for dotenv files
+ */
+function isEnvFile(filePath) {
+  const base = path.basename(String(filePath || ''))
+  return base === '.env' || base.startsWith('.env.') || base.endsWith('.env')
+}
+
+/**
+ * Normalized config file type: '.env' for dotenv files, else the lowercased
+ * extension.
+ * @param {string} filePath - File path or name
+ * @returns {string} File type (e.g. '.yml', '.env', '')
+ */
+function configFileType(filePath) {
+  if (isEnvFile(filePath)) return '.env'
+  return path.extname(String(filePath || '')).toLowerCase()
+}
+
+module.exports = { isEnvFile, configFileType }

package/src/utils/paths/fileType.test.js

@@ -0,0 +1,41 @@
+/* Tests for config file type classification (dotenv detection) */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { isEnvFile, configFileType } = require('./fileType')
+
+test('isEnvFile detects the env-stage-loader precedence names', () => {
+  // .env.{environment}.local, .env.{environment}, .env.local, .env
+  assert.ok(isEnvFile('.env'))
+  assert.ok(isEnvFile('.env.local'))
+  assert.ok(isEnvFile('.env.production'))
+  assert.ok(isEnvFile('.env.production.local'))
+  assert.ok(isEnvFile('/path/to/.env.staging.local'))
+  assert.ok(isEnvFile('deploy.env'))
+})
+
+test('isEnvFile rejects non-dotenv names', () => {
+  assert.is(isEnvFile('config.yml'), false)
+  assert.is(isEnvFile('env.js'), false)
+  assert.is(isEnvFile('environment.json'), false)
+  assert.is(isEnvFile('.environment'), false)
+  assert.is(isEnvFile(''), false)
+})
+
+test('configFileType returns .env for staged dotenv names', () => {
+  assert.is(configFileType('.env.production.local'), '.env')
+  assert.is(configFileType('.env.staging'), '.env')
+})
+
+test('configFileType returns .env for dotenv files', () => {
+  assert.is(configFileType('.env'), '.env')
+  assert.is(configFileType('/x/.env.local'), '.env')
+  assert.is(configFileType('deploy.env'), '.env')
+})
+
+test('configFileType returns lowercased extension otherwise', () => {
+  assert.is(configFileType('config.YML'), '.yml')
+  assert.is(configFileType('data.json'), '.json')
+  assert.is(configFileType('noext'), '')
+})
+
+test.run()

package/src/utils/paths/findLineForKey.js

@@ -31,6 +31,10 @@ function findLineForKey(keyToFind, lines, fileType) {
     if (fileType === '.ini') {
       return new RegExp(`^\\s*${escapedKey}\\s*=`).test(line)
     }
+    // dotenv: KEY= or export KEY=
+    if (fileType === '.env') {
+      return new RegExp(`^\\s*(?:export\\s+)?${escapedKey}\\s*=`).test(line)
+    }
     // JS/TS/ESM: key: or "key": or 'key': or `key`: or [`key`]:
     if (['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(fileType)) {
       return new RegExp(`(?:${escapedKey}|"${escapedKey}"|'${escapedKey}'|\`${escapedKey}\`|\\[\`${escapedKey}\`\\])\\s*:`).test(line)
@@ -55,13 +59,32 @@ function findLineByPath(configPath, lines, fileType) {
 
   const isYaml = fileType === '.yml' || fileType === '.yaml'
   const isJson = fileType === '.json' || fileType === '.json5' || fileType === '.jsonc'
-  if (!isYaml && !isJson) return 0
+  const isEnv = fileType === '.env'
+  if (!isYaml && !isJson && !isEnv) return 0
 
   const segments = configPath.split('.')
+  if (isEnv) return findLineByPathEnv(segments, lines)
   if (isYaml) return findLineByPathYaml(segments, lines)
   return findLineByPathJson(segments, lines)
 }
 
+/**
+ * Find a dotenv key's line. .env is flat, so the key is the first path segment.
+ * Handles leading whitespace and an optional `export ` prefix.
+ * @param {string[]} segments
+ * @param {string[]} lines
+ * @returns {number}
+ */
+function findLineByPathEnv(segments, lines) {
+  const key = segments[0]
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(`^\\s*(?:export\\s+)?${escaped}\\s*=`)
+  for (let li = 0; li < lines.length; li++) {
+    if (pattern.test(lines[li])) return li + 1
+  }
+  return 0
+}
+
 /**
  * @param {string[]} segments
  * @param {string[]} lines

package/src/utils/paths/findLineForKey.test.js

@@ -3,7 +3,7 @@
  */
 const { test } = require('uvu')
 const assert = require('uvu/assert')
-const { findLineForKey } = require('./findLineForKey')
+const { findLineForKey, findLineByPath } = require('./findLineForKey')
 
 // YAML tests
 test('YAML - finds key at start of line', () => {
@@ -123,4 +123,23 @@ test('unknown file type falls back to YAML-style', () => {
   assert.equal(findLineForKey('foo', lines, '.unknown'), 1)
 })
 
+// dotenv
+test('dotenv - finds KEY= line', () => {
+  const lines = ['API_URL=https://x', 'stage=${opt:stage}']
+  assert.equal(findLineForKey('stage', lines, '.env'), 2)
+  assert.equal(findLineForKey('API_URL', lines, '.env'), 1)
+})
+
+test('dotenv - finds export-prefixed and whitespace-padded keys', () => {
+  const lines = ['# comment', 'export TOKEN=abc', '  PADDED = x']
+  assert.equal(findLineForKey('TOKEN', lines, '.env'), 2)
+  assert.equal(findLineForKey('PADDED', lines, '.env'), 3)
+})
+
+test('findLineByPath - dotenv key lookup', () => {
+  const lines = ['A=1', 'stage=${opt:stage}', 'B=2']
+  assert.equal(findLineByPath('stage', lines, '.env'), 2)
+  assert.equal(findLineByPath('missing', lines, '.env'), 0)
+})
+
 test.run()

package/src/utils/setup/applyAnswers.js

@@ -0,0 +1,41 @@
+// Applies setup wizard answer groups onto an in-memory resolution context.
+// The caller chooses the env target (process.env or a plain object copy).
+const dotProp = require('dot-prop')
+
+/**
+ * @typedef {Object} ResolutionContext
+ * @property {Object.<string, any>} options - options hive for ${opt:...} variables
+ * @property {Object.<string, any>} env - env target; pass process.env or a plain object
+ * @property {Object.<string, any>} config - config object under resolution
+ */
+
+/**
+ * Apply answers from the setup wizard to a resolution context
+ * @param {ResolutionContext} context - context to mutate
+ * @param {Object} [answers] - answer groups { options, env, self, dotProp }
+ * @returns {ResolutionContext} the same context, mutated
+ */
+function applyAnswers(context, answers) {
+  if (!answers) return context
+
+  if (answers.options) {
+    Object.assign(context.options, answers.options)
+  }
+  if (answers.env) {
+    Object.assign(context.env, answers.env)
+  }
+  if (answers.self) {
+    Object.assign(context.config, answers.self)
+  }
+  if (answers.dotProp) {
+    for (const [key, value] of Object.entries(answers.dotProp)) {
+      dotProp.set(context.config, key, value)
+    }
+  }
+
+  return context
+}
+
+module.exports = {
+  applyAnswers,
+}

package/src/utils/setup/setupEngine.js

@@ -0,0 +1,85 @@
+// Orchestrates the config setup wizard: analyze config, prompt for missing values,
+// and return grouped answers plus a redacted copy safe for display.
+const path = require('path')
+const { runConfigWizard } = require('../ui/configWizard')
+const { buildConfigRequirements } = require('../requirements/configRequirements')
+const { redactUserInputsByRequirements } = require('../redaction/setupRedaction')
+
+const ANSWER_GROUPS = /** @type {const} */ (['options', 'env', 'self', 'dotProp'])
+
+/**
+ * @typedef {Object} SetupAnswers
+ * @property {Object.<string, any>} options - answers for ${opt:...} variables
+ * @property {Object.<string, any>} env - answers for ${env:...} variables
+ * @property {Object.<string, any>} self - answers for ${self:...} variables
+ * @property {Object.<string, any>} dotProp - answers for dot-prop config references
+ */
+
+/**
+ * @typedef {Object} SetupResult
+ * @property {number} schemaVersion - result shape version
+ * @property {string|null} configPath - absolute path to the config file, null for object input
+ * @property {Array<Object>} requirements - prompt requirements from buildConfigRequirements
+ * @property {SetupAnswers} answers - raw user answers grouped by variable type
+ * @property {SetupAnswers} redactedAnswers - answers with sensitive values redacted for display
+ */
+
+/**
+ * Ensure every answer group exists so callers get a stable shape
+ * @param {Object|undefined} userInputs - answers from the prompt renderer
+ * @returns {SetupAnswers} answers with all groups present
+ */
+function normalizeAnswerGroups(userInputs) {
+  /** @type {SetupAnswers} */
+  const normalized = { options: {}, env: {}, self: {}, dotProp: {} }
+  for (const group of ANSWER_GROUPS) {
+    normalized[group] = Object.assign({}, userInputs && userInputs[group])
+  }
+  return normalized
+}
+
+/**
+ * Run the setup flow: analyze the config, prompt for unresolved values, return answers.
+ * Pure orchestration - applies nothing to process.env, config, or disk.
+ * @param {string|Object} configPathOrObject - path to config file or raw config object
+ * @param {Object} [settings] - configorama settings, plus:
+ * @param {Function} [settings.promptRenderer] - replaces the interactive wizard (mocks, answers files)
+ * @param {Object} [settings.streams] - stream overrides forwarded to the prompt renderer
+ * @param {Object} deps - injected dependencies
+ * @param {Function} [deps.analyze] - configorama.analyze, injected to avoid a require cycle
+ * @param {Object} [deps.analysis] - pre-computed analysis; skips the analyze call
+ * @returns {Promise<SetupResult>} collected answers and requirements
+ */
+async function runSetup(configPathOrObject, settings = {}, deps = {}) {
+  const { analyze } = deps
+  if (!deps.analysis && typeof analyze !== 'function') {
+    throw new Error('setup engine requires an analyze function or a pre-computed analysis')
+  }
+  const { promptRenderer, streams, ...analyzeSettings } = settings
+
+  const analysis = deps.analysis || await analyze(configPathOrObject, analyzeSettings)
+  const requirements = buildConfigRequirements(analysis)
+
+  const configPath = typeof configPathOrObject === 'string'
+    ? path.resolve(configPathOrObject)
+    : null
+
+  const renderPrompts = promptRenderer || runConfigWizard
+  const userInputs = await renderPrompts(analysis, analysis.originalConfig || {}, configPath || '', streams)
+
+  const answers = normalizeAnswerGroups(userInputs)
+  const redactedAnswers = normalizeAnswerGroups(redactUserInputsByRequirements(answers, requirements))
+
+  return {
+    schemaVersion: 1,
+    configPath,
+    requirements,
+    answers,
+    redactedAnswers,
+  }
+}
+
+module.exports = {
+  runSetup,
+  normalizeAnswerGroups,
+}

package/src/utils/setup/stdoutRedirect.js

@@ -0,0 +1,48 @@
+// Temporarily delegates process.stdout writes to another stream so interactive
+// prompt UI can render elsewhere (e.g. stderr) while stdout stays machine-clean.
+
+const MIRRORED_TTY_PROPS = ['rows', 'columns', 'isTTY']
+
+/**
+ * Run fn with all process.stdout writes forwarded to target.
+ * TTY dimensions are mirrored from target so prompt layout matches the
+ * stream it actually renders on (stdout is often a pipe in --export mode).
+ * @param {import('stream').Writable} target - stream that receives the writes
+ * @param {Function} fn - async function to run while redirected
+ * @returns {Promise<any>} fn's result
+ */
+async function withStdoutRedirected(target, fn) {
+  const originalWrite = process.stdout.write
+  const savedDescriptors = {}
+
+  process.stdout.write = /** @type {typeof process.stdout.write} */ (
+    (chunk, encoding, callback) => target.write(chunk, encoding, callback)
+  )
+
+  for (const prop of MIRRORED_TTY_PROPS) {
+    if (target[prop] === undefined) continue
+    savedDescriptors[prop] = Object.getOwnPropertyDescriptor(process.stdout, prop) || null
+    Object.defineProperty(process.stdout, prop, {
+      configurable: true,
+      enumerable: true,
+      get() { return target[prop] },
+    })
+  }
+
+  try {
+    return await fn()
+  } finally {
+    process.stdout.write = originalWrite
+    for (const [prop, descriptor] of Object.entries(savedDescriptors)) {
+      if (descriptor) {
+        Object.defineProperty(process.stdout, prop, descriptor)
+      } else {
+        delete process.stdout[prop]
+      }
+    }
+  }
+}
+
+module.exports = {
+  withStdoutRedirected,
+}