configorama 1.1.0 → 1.2.1

package/src/utils/setup/writeAnswers.js

@@ -0,0 +1,50 @@
+// Writes setup answers to a versioned JSON file for automation (agents, CI).
+// Answers can contain raw secrets, so writes are 0600, atomic, and overwrite-safe.
+const fs = require('fs')
+const path = require('path')
+const { ConfigoramaError } = require('../../errors')
+const { normalizeAnswerGroups } = require('./setupEngine')
+
+/**
+ * Write setup answers to a JSON file
+ * @param {string} filePath - target path
+ * @param {Object} answers - answer groups { options, env, self, dotProp }
+ * @param {Object} [opts] - write behavior
+ * @param {boolean} [opts.force] - overwrite an existing file
+ * @returns {{ path: string, groups: Object.<string, string[]> }} written target and key names per group
+ */
+function writeAnswers(filePath, answers, opts = {}) {
+  if (fs.existsSync(filePath) && !opts.force) {
+    throw new ConfigoramaError(
+      'target_file_exists',
+      `${filePath} already exists. Pass --force to overwrite.`
+    )
+  }
+
+  const normalized = normalizeAnswerGroups(answers)
+  const payload = {
+    schemaVersion: 1,
+    answers: normalized,
+  }
+
+  const dir = path.dirname(filePath)
+  const tmpPath = path.join(dir, `.${path.basename(filePath)}.configx-tmp-${process.pid}`)
+  fs.writeFileSync(tmpPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 })
+  try {
+    fs.renameSync(tmpPath, filePath)
+  } catch (err) {
+    fs.unlinkSync(tmpPath)
+    throw err
+  }
+
+  /** @type {Object.<string, string[]>} */
+  const groups = {}
+  for (const [group, values] of Object.entries(normalized)) {
+    groups[group] = Object.keys(values)
+  }
+  return { path: filePath, groups }
+}
+
+module.exports = {
+  writeAnswers,
+}

package/src/utils/setup/writeDotenv.js

@@ -0,0 +1,142 @@
+// Writes env answers to a dotenv file safely: strict key validation, quoting
+// that round-trips, 0600 permissions, managed-block merge, atomic writes.
+const fs = require('fs')
+const path = require('path')
+const { ConfigoramaError } = require('../../errors')
+
+const MANAGED_BLOCK_START = '# >>> configx setup values >>>'
+const MANAGED_BLOCK_END = '# <<< configx setup values <<<'
+
+const VALID_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/
+const PLAIN_VALUE = /^[A-Za-z0-9_./:@+=-]*$/
+
+/**
+ * Quote a value so common dotenv parsers read it back verbatim
+ * @param {string} value - raw value
+ * @returns {string} dotenv-safe representation
+ */
+function quoteDotenvValue(value) {
+  const str = String(value)
+  if (PLAIN_VALUE.test(str)) return str
+  // Single quotes are literal in dotenv - no expansion of $ or escapes
+  if (!str.includes("'") && !str.includes('\n')) return `'${str}'`
+  const escaped = str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+  return `"${escaped}"`
+}
+
+/**
+ * Render KEY=value lines for the given values
+ * @param {Object.<string, any>} values - env key/value pairs
+ * @returns {string[]} dotenv lines
+ */
+function renderLines(values) {
+  return Object.entries(values).map(([key, value]) => `${key}=${quoteDotenvValue(value)}`)
+}
+
+/**
+ * Replace or append the managed block in existing dotenv content
+ * @param {string} content - current file content
+ * @param {string[]} lines - new KEY=value lines for the block
+ * @param {string} filePath - target path for error messages
+ * @returns {string} updated file content
+ */
+function mergeManagedBlock(content, lines, filePath) {
+  const startCount = content.split(MANAGED_BLOCK_START).length - 1
+  const endCount = content.split(MANAGED_BLOCK_END).length - 1
+
+  if (startCount > 1 || endCount > 1 || startCount !== endCount) {
+    throw new ConfigoramaError(
+      'managed_block_invalid',
+      `Cannot merge into ${filePath}: expected exactly one intact managed block, found ${startCount} start and ${endCount} end marker(s).`
+    )
+  }
+
+  const block = [MANAGED_BLOCK_START, ...lines, MANAGED_BLOCK_END].join('\n')
+
+  if (startCount === 0) {
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n'
+    return `${content}${separator}${block}\n`
+  }
+
+  const startIndex = content.indexOf(MANAGED_BLOCK_START)
+  const endIndex = content.indexOf(MANAGED_BLOCK_END)
+  if (endIndex < startIndex) {
+    throw new ConfigoramaError(
+      'managed_block_invalid',
+      `Cannot merge into ${filePath}: managed block markers are out of order.`
+    )
+  }
+  return content.slice(0, startIndex) + block + content.slice(endIndex + MANAGED_BLOCK_END.length)
+}
+
+/**
+ * Write values atomically: temp file in the same directory, then rename
+ * @param {string} filePath - target path
+ * @param {string} content - file content
+ * @param {number} mode - file mode for new files
+ */
+function atomicWrite(filePath, content, mode) {
+  const dir = path.dirname(filePath)
+  const tmpPath = path.join(dir, `.${path.basename(filePath)}.configx-tmp-${process.pid}`)
+  fs.writeFileSync(tmpPath, content, { mode })
+  try {
+    fs.renameSync(tmpPath, filePath)
+  } catch (err) {
+    fs.unlinkSync(tmpPath)
+    throw err
+  }
+}
+
+/**
+ * Write env answers to a dotenv file
+ * @param {string} filePath - target dotenv path
+ * @param {Object.<string, any>} values - env key/value pairs to write
+ * @param {Object} [opts] - write behavior
+ * @param {boolean} [opts.merge] - replace/append the managed block, preserving other content
+ * @param {boolean} [opts.force] - overwrite the whole file if it exists
+ * @returns {{ path: string, keys: string[] }} written target and key names for summaries
+ */
+function writeDotenv(filePath, values, opts = {}) {
+  const keys = Object.keys(values || {})
+  for (const key of keys) {
+    if (!VALID_KEY.test(key)) {
+      throw new ConfigoramaError(
+        'invalid_env_key',
+        `Cannot write "${key}" to ${filePath}: dotenv keys must match ${VALID_KEY}.`
+      )
+    }
+  }
+
+  const lines = renderLines(values)
+  const exists = fs.existsSync(filePath)
+
+  if (exists && !opts.merge && !opts.force) {
+    throw new ConfigoramaError(
+      'target_file_exists',
+      `${filePath} already exists. Pass --merge to update the managed block or --force to overwrite.`
+    )
+  }
+
+  let content
+  let mode = 0o600
+  if (opts.merge) {
+    const existingContent = exists ? fs.readFileSync(filePath, 'utf8') : ''
+    if (exists) mode = fs.statSync(filePath).mode & 0o777
+    content = mergeManagedBlock(existingContent, lines, filePath)
+  } else {
+    content = `${lines.join('\n')}\n`
+  }
+
+  atomicWrite(filePath, content, mode)
+  return { path: filePath, keys }
+}
+
+module.exports = {
+  writeDotenv,
+  quoteDotenvValue,
+  MANAGED_BLOCK_START,
+  MANAGED_BLOCK_END,
+}

package/src/utils/ui/configWizard.js

@@ -8,6 +8,7 @@ const { toClickablePath } = require('./createEditorLink')
 const { buildConfigRequirements } = require('../requirements/configRequirements')
 const { createPromptDescriptors } = require('./promptDescriptors')
 const { isSensitiveVariable } = require('../redaction/redact')
+const { withStdoutRedirected } = require('../setup/stdoutRedirect')
 
 const INVISIBLE_SPACE = '\u2800\u2800\u2800'
 
@@ -613,9 +614,27 @@ function createPromptMessage(varInfo) {
  * Runs config setup wizard
  * @param {object} metadata - Enriched metadata from configorama
  * @param {object} originalConfig - The original config before resolution
+ * @param {string} [configFilePath] - Path to the config file for display
+ * @param {object} [streams] - Stream overrides for the prompt UI
+ * @param {import('stream').Writable} [streams.output] - Where prompt UI renders; stdout stays clean when set
  * @returns {Promise<object>} User inputs by variable type
  */
-async function runConfigWizard(metadata, originalConfig = {}, configFilePath = '') {
+async function runConfigWizard(metadata, originalConfig = {}, configFilePath = '', streams) {
+  const output = streams && streams.output
+  if (output && output !== process.stdout) {
+    return withStdoutRedirected(output, () => renderConfigWizard(metadata, originalConfig, configFilePath))
+  }
+  return renderConfigWizard(metadata, originalConfig, configFilePath)
+}
+
+/**
+ * Renders the wizard prompts on process.stdout
+ * @param {object} metadata - Enriched metadata from configorama
+ * @param {object} originalConfig - The original config before resolution
+ * @param {string} [configFilePath] - Path to the config file for display
+ * @returns {Promise<object>} User inputs by variable type
+ */
+async function renderConfigWizard(metadata, originalConfig = {}, configFilePath = '') {
   const { uniqueVariables } = metadata
 
   if (!uniqueVariables || Object.keys(uniqueVariables).length === 0) {

package/types/src/capabilities.d.ts

@@ -0,0 +1,8 @@
+export const SCHEMA_VERSION: 1;
+export const VIEWS: string[];
+/**
+ * Build the capabilities contract object.
+ * @returns {object} stable, deterministic description of the CLI surface
+ */
+export function buildCapabilities(): object;
+//# sourceMappingURL=capabilities.d.ts.map

package/types/src/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/capabilities.js"],"names":[],"mappings":"AAOA,6BAAuB,CAAC,CAAA;AAExB,6BAAgD;AAEhD;;;GAGG;AACH,qCAFa,MAAM,CA2ClB"}

package/types/src/display.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Display "No Variables Found" message
+ * @param {string} configFilePath
+ * @param {RegExp} variableSyntax
+ * @param {Object} variableTypes
+ */
+export function displayNoVariablesFound(configFilePath: string, variableSyntax: RegExp, variableTypes: any): void;
+/**
+ * Display variable details in stacked box format
+ * @param {Object} params
+ * @param {string[]} params.varKeys
+ * @param {Object} params.variableData
+ * @param {Object} params.uniqueVariables
+ * @param {RegExp} params.varPrefixPattern
+ * @param {RegExp} params.varSuffixPattern
+ * @param {string[]} params.lines
+ * @param {string} params.fileType
+ * @param {string} params.configFilePath
+ */
+export function displayVariableDetails({ varKeys, variableData, uniqueVariables, varPrefixPattern, varSuffixPattern, lines, fileType, configFilePath }: {
+    varKeys: string[];
+    variableData: any;
+    uniqueVariables: any;
+    varPrefixPattern: RegExp;
+    varSuffixPattern: RegExp;
+    lines: string[];
+    fileType: string;
+    configFilePath: string;
+}): void;
+/**
+ * Display unique variables in stacked box format
+ * @param {Object} params
+ * @param {string[]} params.uniqueVarKeys
+ * @param {Object} params.uniqueVariables
+ * @param {string[]} params.lines
+ * @param {string} params.fileType
+ * @param {string} params.configFilePath
+ */
+export function displayUniqueVariables({ uniqueVarKeys, uniqueVariables, lines, fileType, configFilePath }: {
+    uniqueVarKeys: string[];
+    uniqueVariables: any;
+    lines: string[];
+    fileType: string;
+    configFilePath: string;
+}): void;
+/**
+ * Display configurable variables grouped by source type
+ * @param {Object} params
+ * @param {string[]} params.uniqueVarKeys
+ * @param {Object} params.uniqueVariables
+ * @param {string[]} params.lines
+ * @param {string} params.fileType
+ * @param {string} params.configFilePath
+ */
+export function displayConfigurableVariables({ uniqueVarKeys, uniqueVariables, lines, fileType, configFilePath }: {
+    uniqueVarKeys: string[];
+    uniqueVariables: any;
+    lines: string[];
+    fileType: string;
+    configFilePath: string;
+}): void;
+//# sourceMappingURL=display.d.ts.map

package/types/src/display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../../src/display.js"],"names":[],"mappings":"AAiEA;;;;;GAKG;AACH,wDAJW,MAAM,kBACN,MAAM,4BAwBhB;AAED;;;;;;;;;;;GAWG;AACH,wJATG;IAAyB,OAAO,EAAxB,MAAM,EAAE;IACO,YAAY;IACZ,eAAe;IACf,gBAAgB,EAA/B,MAAM;IACS,gBAAgB,EAA/B,MAAM;IACW,KAAK,EAAtB,MAAM,EAAE;IACO,QAAQ,EAAvB,MAAM;IACS,cAAc,EAA7B,MAAM;CAChB,QAiKA;AAED;;;;;;;;GAQG;AACH,4GANG;IAAyB,aAAa,EAA9B,MAAM,EAAE;IACO,eAAe;IACb,KAAK,EAAtB,MAAM,EAAE;IACO,QAAQ,EAAvB,MAAM;IACS,cAAc,EAA7B,MAAM;CAChB,QAmHA;AAED;;;;;;;;GAQG;AACH,kHANG;IAAyB,aAAa,EAA9B,MAAM,EAAE;IACO,eAAe;IACb,KAAK,EAAtB,MAAM,EAAE;IACO,QAAQ,EAAvB,MAAM;IACS,cAAc,EAA7B,MAAM;CAChB,QA2IA"}

package/types/src/errors.d.ts

@@ -0,0 +1,20 @@
+export const ERROR_CODES: {
+    code: string;
+    description: string;
+}[];
+export class ConfigoramaError extends Error {
+    constructor(code: any, message: any, details?: {});
+    code: any;
+    details: {};
+    toJSON(): {
+        error: {
+            code: any;
+            message: string;
+            details: {};
+        };
+    };
+}
+export function classifyErrorMessage(message: any, fallbackCode?: string): string;
+export function isConfigoramaError(error: any): boolean;
+export function normalizeError(error: any, fallbackCode?: string): any;
+//# sourceMappingURL=errors.d.ts.map

package/types/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.js"],"names":[],"mappings":"AAGA;;;IAmBC;AAED;IACE,mDAKC;IAFC,UAAuC;IACvC,YAAsB;IAGxB;;;;;;MAQC;CACF;AAgBD,kFAUC;AAxBD,wDAEC;AAED,uEAQC"}

package/types/src/index.d.ts

@@ -5,6 +5,99 @@ declare function _exports<T = any>(configPathOrObject: string | any, settings?:
 declare namespace _exports {
     export function sync<T = any>(configPathOrObject: string | any, settings?: ConfigoramaSettings): T;
     export function analyze(configPathOrObject: string | object, settings?: object): Promise<any>;
+    export function setup(configPathOrObject: string | any, settings?: object): Promise<object>;
+    export { writeDotenv };
+    export { writeAnswers };
+    export function introspect(configPathOrObject: any, settings?: {}): Promise<{
+        schemaVersion: number;
+        nodes: ({
+            id: string;
+            kind: string;
+            variable: any;
+            variableType: any;
+            sourceClass: any;
+            risk: string;
+            severity: string;
+            paths: any[];
+            sensitive: boolean;
+        } | {
+            id: string;
+            kind: string;
+            path: any;
+            relativePath: any;
+            exists: any;
+            risk: string;
+            severity: string;
+        })[];
+        edges: {
+            from: string;
+            to: string;
+            kind: string;
+        }[];
+        diagnostics: {
+            code: string;
+            severity: string;
+            variable: any;
+            message: string;
+        }[];
+        summary: {
+            nodes: number;
+            edges: number;
+            diagnostics: number;
+        };
+    }>;
+    export function audit(configPathOrObject: any, settings?: {}): Promise<{
+        schemaVersion: number;
+        safeMode: boolean;
+        findings: any[];
+        diagnostics: any;
+        summary: {
+            high: number;
+            medium: number;
+            low: number;
+            info: number;
+            total: number;
+        };
+    }>;
+    export function graph(configPathOrObject: any, settings?: {}): Promise<string | {
+        schemaVersion: number;
+        nodes: ({
+            id: string;
+            kind: string;
+            variable: any;
+            variableType: any;
+            sourceClass: any;
+            risk: string;
+            severity: string;
+            paths: any[];
+            sensitive: boolean;
+        } | {
+            id: string;
+            kind: string;
+            path: any;
+            relativePath: any;
+            exists: any;
+            risk: string;
+            severity: string;
+        })[];
+        edges: {
+            from: string;
+            to: string;
+            kind: string;
+        }[];
+        diagnostics: {
+            code: string;
+            severity: string;
+            variable: any;
+            message: string;
+        }[];
+        summary: {
+            nodes: number;
+            edges: number;
+            diagnostics: number;
+        };
+    }>;
+    export function inspect(configPathOrObject: string | object, settings?: object): Promise<object | string>;
     export { parsers as format };
     export { Configorama };
     export { buildVariableSyntax };
@@ -49,6 +142,18 @@ type ConfigoramaSettings = {
      * - allow undefined values to pass through without throwing errors
      */
     allowUndefinedValues?: boolean;
+    /**
+     * - glob-like config paths whose values should be left verbatim
+     */
+    ignorePaths?: string[];
+    /**
+     * - alias for ignorePaths
+     */
+    skipResolutionPaths?: string[];
+    /**
+     * - disable built-in CloudFormation and embedded-code ignore paths
+     */
+    disableDefaultIgnorePaths?: boolean;
     /**
      * - values passed into .js config files if user using javascript config
      */
@@ -57,6 +162,14 @@ type ConfigoramaSettings = {
      * - return both config and metadata about variables found
      */
     returnMetadata?: boolean;
+    /**
+     * - suppress env-stage-loader logs when useDotenv/useDotEnv is enabled
+     */
+    dotEnvSilent?: boolean;
+    /**
+     * - enable env-stage-loader debug logs when useDotenv/useDotEnv is enabled
+     */
+    dotEnvDebug?: boolean;
     /**
      * - keys to merge in arrays of objects
      */
@@ -67,6 +180,10 @@ type ConfigoramaSettings = {
     filePathOverrides?: {
         [x: string]: string;
     };
+    /**
+     * - install Configorama CLI signal handlers. Defaults to false for library calls.
+     */
+    handleSignalEvents?: boolean;
 };
 type ConfigoramaResult<T = any> = {
     /**
@@ -96,6 +213,8 @@ type ConfigoramaResult<T = any> = {
      */
     resolutionHistory: any;
 };
+import { writeDotenv } from "./utils/setup/writeDotenv";
+import { writeAnswers } from "./utils/setup/writeAnswers";
 import parsers = require("./parsers");
 import Configorama = require("./main");
 import { buildVariableSyntax } from "./utils/variables/variableUtils";

package/types/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.js"],"names":[],"mappings":";;;AAuCiB,0BALH,CAAC,4BACJ,MAAM,MAAO,aACb,mBAAmB,GACjB,OAAO,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAiD7C;;IASqB,qBALR,CAAC,4BACJ,MAAM,MAAO,aACb,mBAAmB,GACjB,CAAC,CAgBb;IAQwB,4CAJb,MAAM,GAAC,MAAM,aACd,MAAM,gBAUhB;;;;;;;;;;;;;;;;aApHa,MAAM;;;;gBACN,MAAM;;;;;;;;;;;;;;;;;;;;uBAIN,OAAO;;;;2BACP,OAAO;;;;kBACP,cAAe;;;;qBACf,OAAO;;;;gBACP,MAAM,EAAE;;;;;;;;uBAKR,CAAC;;;;oBAED,MAAM;;;;;;;;;;YAEN,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.js"],"names":[],"mappings":";;;AAwDiB,0BALH,CAAC,4BACJ,MAAM,MAAO,aACb,mBAAmB,GACjB,OAAO,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAiD7C;;IASqB,qBALR,CAAC,4BACJ,MAAM,MAAO,aACb,mBAAmB,GACjB,CAAC,CAgBb;IAQwB,4CAJb,MAAM,GAAC,MAAM,aACd,MAAM,gBAchB;IAQsB,0CAJZ,MAAM,MAAO,aACb,MAAM,GACL,OAAO,CAAC,MAAM,CAAC,CAI1B;;;IAQ2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAS3B;IAEsB;;;;;;;;;;;;OAyBtB;IAEsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAItB;IAUwB,4CAJd,MAAM,GAAC,MAAM,aACb,MAAM,GACL,OAAO,CAAC,MAAM,GAAC,MAAM,CAAC,CAiCjC;;;;;;;;;;;;;;;;aAnOa,MAAM;;;;gBACN,MAAM;;;;;;;;;;;;;;;;;;;;uBAIN,OAAO;;;;2BACP,OAAO;;;;kBACP,MAAM,EAAE;;;;0BACR,MAAM,EAAE;;;;gCACR,OAAO;;;;kBACP,cAAe;;;;qBACf,OAAO;;;;mBACP,OAAO;;;;kBACP,OAAO;;;;gBACP,MAAM,EAAE;;;;;;;;;;yBAER,OAAO;;uBAIP,CAAC;;;;oBAED,MAAM;;;;;;;;;;YAEN,CAAC"}

package/types/src/main.d.ts

@@ -1,18 +1,35 @@
 export = Configorama;
 declare class Configorama {
     constructor(fileOrObject: any, opts: any);
+    setupMode: boolean;
     settings: any;
+    safetyPolicy: {
+        safeMode: boolean;
+        blockExecutableFiles: boolean;
+        blockCustomResolvers: boolean;
+        blockCustomFunctions: boolean;
+        blockDotEnv: boolean;
+        restrictFileRoots: boolean;
+        allowedFileRoots: string[];
+    };
     filterCache: {};
     _originalValueCache: Map<any, any>;
+    _resolvedPaths: Set<any>;
+    _ignorePathCache: Map<any, any>;
+    _fileContentCache: Map<any, any>;
+    _needsRawClone: boolean;
     foundVariables: any[];
     fileRefsFound: any[];
     resolutionTracking: {};
+    _trackCalls: boolean;
     variableSyntax: RegExp;
+    variableSyntaxTest: RegExp;
     varPrefix: string;
     varSuffix: string;
     varPrefixPattern: RegExp;
     varSuffixPattern: RegExp;
     varSuffixWithSpacePattern: RegExp;
+    ignorePathPatterns: string[][];
     rawOriginalConfig: any;
     config: any;
     originalConfig: any;
@@ -23,6 +40,7 @@ declare class Configorama {
     tracker: PromiseTracker;
     variableTypes: any;
     variablesKnownTypes: RegExp;
+    subResolvableTypes: RegExp;
     _resolverByPrefix: Map<any, any>;
     filters: any;
     filterMatch: RegExp;
@@ -59,27 +77,13 @@ declare class Configorama {
     configFileContents: string;
     _markdownContent: any;
     _markdownContentKey: string;
+    setupRequirements: any[];
     /**
      * Collect metadata about all variables found in the configuration
      * @returns {object} Metadata object containing variables, fileRefs, and summary
      */
     collectVariableMetadata(): object;
-    _cachedMetadata: {
-        variables: {};
-        uniqueVariables: {};
-        fileDependencies: {
-            globPatterns: any[];
-            dynamicPaths: any[];
-            resolvedPaths: any[];
-            byConfigPath: any[];
-            references: any[];
-        };
-        summary: {
-            totalVariables: number;
-            requiredVariables: number;
-            variablesWithDefaults: number;
-        };
-    };
+    _cachedMetadata: any;
     /**
      * Populate the variables in the given object.
      * @param objectToPopulate The object to populate variables within.
@@ -87,6 +91,9 @@ declare class Configorama {
      */
     populateObject(objectToPopulate: any): Promise<any>;
     populateObjectImpl(objectToPopulate: any): any;
+    isIgnorePath(pathValue: any): any;
+    hasSubResolvableToken(value: any): boolean;
+    shouldSkipResolution(pathValue: any, value: any): boolean;
     /**
      * The declaration of a terminal property.  This declaration includes the path and value of the
      * property.

package/types/src/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.js"],"names":[],"mappings":";AA0GA;IACE,0CA2dC;IAndC,cAcW;IAuBX,gBAAqB;IAErB,mCAAoC;IAEpC,sBAAwB;IACxB,qBAAuB;IAGvB,uBAA4B;IAsB5B,uBAAoC;IAIpC,kBAAqC;IACrC,kBAAqC;IAErC,yBAA+F;IAC/F,yBAAuD;IACvD,kCAAyE;IAKvE,uBAAgD;IAKhD,YAAuB;IAEvB,oBAA0C;IAE1C,gBAAoD;IAOpD,uBAAkC;IAElC,uBAA8B;IAE9B,uBAAkC;IASpC,wBAAmC;IAGnC,mBAqHC;IAwED,4BAA8C;IAG9C,iCAAkC;IAalC,aA2EC;IAUD,oBAEC;IAGD,eAiDC;IAOD,YAAc;IACd,cAAgB;IAChB,kBAAkB;IAGpB;;;;OAIG;IACH,0BAHW,MAAM,GACJ,OAAO,CAQnB;IAED;;;;OAIG;IACH,6BAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAOvB;IAED;;;;OAIG;IACH,gCAHW,MAAM,GACJ,OAAO,CA2BnB;IAKD;;;;;OAKG;IACH,oBAFa,OAAO,CAAC,GAAG,CAAC,CA6vBxB;IA1vBC,aAA4B;IAc1B,2BAA4B;IAmB1B,sBAA0C;IAC1C,4BAAkC;IA0tBxC;;;OAGG;IACH,2BAFa,MAAM,CA6alB;IAvBC;;;;;;;;;;;;;;;MAoBC;IAIH;;;;OAIG;IACH,uCAFa,OAAO,CAAC,GAAG,CAAC,CAIxB;IACD,+CAsBC;IAKD;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;OAWG;IACH,mFAHa;;;;cAZC,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAWD,CA6E9B;IACD;;;OAGG;IACH;;;;;OAKG;IACH,oCAHa,OAAO,CAAC;;;;cAjGP,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAgGgB,CAAC,EAAE,CA6BlD;IACD;;;;;OAKG;IACH,iDAFa,OAAO,CAAC,IAAI,CAAC,CAWzB;IAID;;;;;OAKG;IACH;;;;OAIG;IACH,2BAFa,eAAc;;;;;;;;;;OAAa,CAavC;IACD;;;;;OAKG;IACH,yBAHW;;;;;;;;;;OAAa,gCACX,cAAS,CAOrB;IACD;;;;;;OAMG;IACH,6DAFa,GAAC,CAiLb;IAKD;;;;;;;OAOG;IACH,yDAHa,OAAO,CAAC,GAAG,CAAC,CAiCxB;IACD;;;;OAIG;IAOH;;;;;;OAMG;IACH,wFA2BC;IACD;;;;;;;;;;;OAWG;IACH,8BARG;QAAyB,KAAK,EAAtB,GAAG;QACoB,IAAI,GAA3B,MAAM,EAAE;QACa,cAAc,GAAnC,MAAM;QACc,iBAAiB;KAC7C,6CAEU;QAAC,KAAK,EAAE,GAAG,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,QAAQ;QAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAsa9J;IAID;;;;;;;;OAQG;IACH,qEAHa,OAAO,CAAC,GAAG,CAAC,CAoExB;IAKD;;;;;;;OAOG;IACH,0FAFa,OAAO,CAAC,GAAG,CAAC,CAiiBxB;IACD,+EA+BC;IACD,yDAiBC;IACD,oEA6BC;IAKD,8CAQC;IACD,kDAyBC;IACD;;;;;;;;;;;;;OAaG;IACH,wEAoDC;IAKD,4BAOC;IACD,sCAqEC;CACF"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.js"],"names":[],"mappings":"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"}

package/types/src/metadata.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Collect metadata about all variables found in the configuration
+ * @param {Object} params
+ * @param {RegExp} params.variableSyntax
+ * @param {Object} params.variablesKnownTypes
+ * @param {Object} params.variableTypes
+ * @param {RegExp|null} params.filterMatch
+ * @param {string} params.configFilePath
+ * @param {Object} params.displayConfig - rawOriginalConfig || originalConfig, used for traversal
+ * @param {Object} params.originalConfig - this.originalConfig, used for dotProp.get checks
+ * @param {string} params.varSuffix
+ * @param {RegExp} params.varSuffixWithSpacePattern
+ * @param {string[][]} [params.ignorePathPatterns]
+ * @returns {Object} Metadata object containing variables, fileDependencies, and summary
+ */
+export function collectVariableMetadata({ variableSyntax, variablesKnownTypes, variableTypes, filterMatch, configFilePath, displayConfig, originalConfig, varSuffix, varSuffixWithSpacePattern, ignorePathPatterns, }: {
+    variableSyntax: RegExp;
+    variablesKnownTypes: any;
+    variableTypes: any;
+    filterMatch: RegExp | null;
+    configFilePath: string;
+    displayConfig: any;
+    originalConfig: any;
+    varSuffix: string;
+    varSuffixWithSpacePattern: RegExp;
+    ignorePathPatterns?: string[][];
+}): any;
+//# sourceMappingURL=metadata.d.ts.map

package/types/src/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/metadata.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH,uNAZG;IAAuB,cAAc,EAA7B,MAAM;IACS,mBAAmB;IACnB,aAAa;IACR,WAAW,EAA/B,MAAM,GAAC,IAAI;IACI,cAAc,EAA7B,MAAM;IACS,aAAa;IACb,cAAc;IACd,SAAS,EAAxB,MAAM;IACS,yBAAyB,EAAxC,MAAM;IACc,kBAAkB,GAAtC,MAAM,EAAE,EAAE;CAClB,OAgbF"}

package/types/src/parsers/dotenv.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @param {string} contents - Raw .env file text
+ * @returns {Object} Flat map of KEY -> raw string value
+ */
+export function parse(contents: string): any;
+//# sourceMappingURL=dotenv.d.ts.map

package/types/src/parsers/dotenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv.d.ts","sourceRoot":"","sources":["../../../src/parsers/dotenv.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,gCAHW,MAAM,OAKhB"}

package/types/src/parsers/esm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"esm.d.ts","sourceRoot":"","sources":["../../../src/parsers/esm.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,yCAJW,MAAM,eAEJ,OAAO,CAAC,GAAC,CAAC,CAmBtB;AAED;;;;;GAKG;AACH,6CAJW,MAAM,eAEJ,GAAC,CAkBb"}
+{"version":3,"file":"esm.d.ts","sourceRoot":"","sources":["../../../src/parsers/esm.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,yCAJW,MAAM,eAEJ,OAAO,CAAC,GAAC,CAAC,CAItB;AAED;;;;;GAKG;AACH,6CAJW,MAAM,eAEJ,GAAC,CAkBb"}

package/types/src/parsers/typescript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../../src/parsers/typescript.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,gDAJW,MAAM,eAEJ,OAAO,CAAC,GAAC,CAAC,CAmDtB;AAED;;;;;GAKG;AACH,oDAJW,MAAM,eAEJ,GAAC,CAmDb"}
+{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../../src/parsers/typescript.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,gDAJW,MAAM,eAEJ,OAAO,CAAC,GAAC,CAAC,CAItB;AAED;;;;;GAKG;AACH,oDAJW,MAAM,eAEJ,GAAC,CAmDb"}

package/types/src/resolvers/valueFromCron.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"valueFromCron.d.ts","sourceRoot":"","sources":["../../../src/resolvers/valueFromCron.js"],"names":[],"mappings":"AACA,oCAAkF;AAiNlF,8EAiCC;AAhPD;;;GAGG;AACH,sDAyMC"}
+{"version":3,"file":"valueFromCron.d.ts","sourceRoot":"","sources":["../../../src/resolvers/valueFromCron.js"],"names":[],"mappings":"AACA,oCAAkF;AA4LlF,8EAiCC;AA3ND;;;GAGG;AACH,sDAoLC"}

package/types/src/resolvers/valueFromEval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"valueFromEval.d.ts","sourceRoot":"","sources":["../../../src/resolvers/valueFromEval.js"],"names":[],"mappings":"AAQA,gDAIC;AAXD,oCAA+C;AAyC/C,qEA6CC"}
+{"version":3,"file":"valueFromEval.d.ts","sourceRoot":"","sources":["../../../src/resolvers/valueFromEval.js"],"names":[],"mappings":"AASA,gDAIC;AAZD,oCAA+C;AA0C/C,qEAsDC"}

package/types/src/resolvers/valueFromFile.d.ts

@@ -14,6 +14,8 @@
  * @param {RegExp} ctx.textRefSyntax - Regex for text() syntax
  * @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>}
@@ -32,6 +34,8 @@ export function getValueFromFile(ctx: {
     textRefSyntax: RegExp;
     varPrefix: string;
     varSuffix: string;
+    fileContentCache?: Map<string, string>;
+    safetyPolicy?: object;
 }, variableString: string, options: object): Promise<any>;
 /**
  * Parse file contents based on file extension