configorama 1.1.0 → 1.2.1

package/README.md

@@ -2304,7 +2304,16 @@ stage: ${opt:stage | help('Deployment stage, e.g. dev or prod')}
 
 The [Variable Source Types](#variable-source-types) table describes how the wizard treats each source.
 
-> **Experimental:** the wizard fills in values for the current resolution run only. It does not write your answers back to the config file yet.
+The wizard prints a summary of your answers with sensitive values redacted, applies them to the current resolution run, and never edits the source config file.
+
+Programmatic access to the same engine returns the answers without applying them anywhere:
+
+```javascript
+const result = await configorama.setup('config.yml')
+// { schemaVersion, configPath, requirements, answers, redactedAnswers }
+```
+
+To apply answers to explicit targets - your current shell, a one-off command, a `.env.local`, or a JSON answers file - use [`configx setup`](./packages/configx/README.md#setup-wizard). Its safe write behavior (0600 permissions, managed-block merge, sensitive-value confirmation) is built on the same engine.
 
 ---
 

package/cli.js

@@ -61,7 +61,8 @@ Commands:
   (default)                 Resolve <file> and print the result
   inspect <file>            Introspect a config without resolving it (full model)
                               --view requirements|audit|graph for a single slice
-  setup <file>              Run the interactive config wizard (experimental)
+  setup <file>              Prompt for missing config values, then resolve with the
+                              answers applied (summary redacts sensitive values)
   capabilities              Print the machine-readable CLI contract (JSON)
 
 Options:
@@ -449,6 +450,17 @@ if (requirementsMode) {
 // Process the configuration
 const shouldRedactSetupStdout = options.setup && !argv.output && !argv.copy
 let setupRequirementsForRedaction = []
+
+// If stdin ends mid-wizard the pending prompt promise never settles, the event
+// loop drains, and node would exit 0 as if setup succeeded. Fail closed instead.
+const onSetupBeforeExit = () => {
+  process.stderr.write('configorama: setup cancelled (input ended before completion)\n')
+  process.exit(1)
+}
+if (options.setup) {
+  process.on('beforeExit', onSetupBeforeExit)
+}
+
 const configPromise = shouldRedactSetupStdout
   ? (() => {
       const instance = new Configorama(inputFile, options)
@@ -461,6 +473,7 @@ const configPromise = shouldRedactSetupStdout
 
 configPromise
   .then((config) => {
+    process.removeListener('beforeExit', onSetupBeforeExit)
     let outputConfig = shouldRedactSetupStdout
       ? redactConfigByRequirements(config, setupRequirementsForRedaction)
       : config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -17,7 +17,6 @@
     "types",
     "index.d.ts",
     "package.json",
-    "package-lock.json",
     "README.md",
     "!plugins/*/*.test.js",
     "!plugins/*/example",
@@ -48,7 +47,10 @@
     "publish": "git push origin && git push origin --tags",
     "release:patch": "npm version patch && npm publish",
     "release:minor": "npm version minor && npm publish",
-    "release:major": "npm version major && npm publish"
+    "release:major": "npm version major && npm publish",
+    "release": "lerna publish",
+    "version:all": "lerna version --no-push --no-git-tag-version",
+    "test:all": "pnpm -r test"
   },
   "author": "David Wells",
   "license": "MIT",
@@ -82,6 +84,7 @@
   "devDependencies": {
     "@cdktf/hcl2json": "^0.21.0",
     "@types/node": "^24.10.1",
+    "lerna": "^9.0.0",
     "markdown-magic": "^4.8.0",
     "tsx": "^4.7.0",
     "typescript": "^5.8.3",
@@ -106,5 +109,7 @@
     "ts-node": {
       "optional": true
     }
-  }
+  },
+  "packageManager": "pnpm@10.33.0",
+  "gitHead": "2ce70bfa849433ba74c60fa3c1cd3dba942b6556"
 }

package/plugins/onepassword/index.js

@@ -1,7 +1,7 @@
 /* 1Password variable source for configorama
    Resolves ${op:alias} and ${op(item)} references through the op CLI */
 const { readSecretRef, getItem } = require('./op-cli')
-const { validateAliasName, normalizeRefValue } = require('./normalize')
+const { validateAliasName, normalizeRefValue, isItemId } = require('./normalize')
 const { selectField, trySelectField } = require('./fields')
 const { parseStructuredSecret, getKeyPath } = require('./parser')
 
@@ -173,10 +173,21 @@ function createOnePasswordResolver(options = {}) {
 
     validateAliasName(alias)
     const reference = aliasRefs[alias]
-    if (!reference) {
-      throw new Error(`Unknown 1Password alias "${alias}". Configure refs.${alias}.`)
+    if (reference) {
+      return { reference, keyPath, alias }
     }
-    return { reference, keyPath, alias }
+    // Not a configured alias. A bare 1Password item ID (26-char base32) is
+    // unambiguous, so accept it as a direct item reference. Configured aliases
+    // always take precedence (checked above), so this only affects strings that
+    // would otherwise error as an unknown alias.
+    if (isItemId(alias)) {
+      return {
+        reference: { kind: 'item', item: alias, vault: undefined, section: undefined, field: undefined },
+        keyPath,
+        alias: undefined,
+      }
+    }
+    throw new Error(`Unknown 1Password alias "${alias}". Configure refs.${alias}.`)
   }
 
   /**

package/plugins/onepassword/normalize.js

@@ -2,8 +2,20 @@
    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.
@@ -142,4 +154,4 @@ function normalizeObjectRef(value) {
   }
 }
 
-module.exports = { validateAliasName, normalizeRefValue, parsePrivateLink, isPrivateLink }
+module.exports = { validateAliasName, normalizeRefValue, parsePrivateLink, isPrivateLink, isItemId }

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,

package/src/main.js

@@ -110,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 */
@@ -176,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
 
@@ -188,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
@@ -940,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')

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

@@ -8,6 +8,7 @@ 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')
@@ -23,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

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,
+}