configorama 1.0.1 → 1.1.0

package/plugins/onepassword/normalize.js

@@ -0,0 +1,145 @@
+/* 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_]+$/
+const PRIVATE_LINK_PREFIXES = ['https://start.1password.com/open/i', 'onepassword://open/i']
+
+/**
+ * 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 }

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/index.js

@@ -163,7 +163,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')
@@ -2574,8 +2575,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 +3050,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/metadata.js

@@ -9,6 +9,7 @@ const { normalizePath, extractFilePath, resolveInnerVariables } = require('./uti
 const { shouldIgnorePath } = require('./utils/paths/ignorePaths')
 const { findNestedVariables } = require('./utils/variables/findNestedVariables')
 const { splitOnPipe } = require('./utils/strings/splitOnPipe')
+const { applyDotenvFileRefMetadata } = require('./utils/security/dotenvFileRefs')
 
 /**
  * Collect metadata about all variables found in the configuration
@@ -329,6 +330,12 @@ function collectVariableMetadata({
               containsVariables,
               exists: fileExists,
             }
+            applyDotenvFileRefMetadata(configPathEntry, {
+              filePath: absolutePath,
+              relativePath: resolvedPath,
+              originalVariableString: rawValue,
+              resolvedVariableString: resolvedVarString,
+            })
             if (globPattern) {
               configPathEntry.pattern = globPattern
             }

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

@@ -9,6 +9,7 @@ const { findNestedVariables } = require('../utils/variables/findNestedVariables'
 const { makeBox } = require('@davidwells/box-logger')
 const { encodeJsSyntax, decodeJsonInVariable, hasEncodedJson } = require('../utils/encoders/js-fixes')
 const { checkFileAccess } = require('../utils/security/safetyPolicy')
+const { applyDotenvFileRefMetadata, isIniLikeFilePath } = require('../utils/security/dotenvFileRefs')
 
 /* File Parsers */
 const YAML = require('../parsers/yaml')
@@ -85,7 +86,7 @@ function parseFileContents(content, filePath) {
   if (ext === 'toml' || ext === 'tml') {
     return TOML.parse(content)
   }
-  if (isIniLikeExtension(ext)) {
+  if (isIniLikeExtension(ext, filePath)) {
     return INI.parse(content)
   }
 
@@ -93,8 +94,8 @@ function parseFileContents(content, filePath) {
   return content
 }
 
-function isIniLikeExtension(ext) {
-  return ext === 'ini' || ext === 'env'
+function isIniLikeExtension(ext, filePath) {
+  return ext === 'ini' || ext === 'env' || isIniLikeFilePath(filePath)
 }
 
 /**
@@ -205,6 +206,14 @@ async function getValueFromFile(ctx, variableString, options) {
     containsVariables: options.context.value !== options.context.originalSource,
     exists,
   }
+  applyDotenvFileRefMetadata(fileRefEntry, {
+    filePath: fullFilePath,
+    relativePath,
+    resolvedPath,
+    variableString,
+    originalVariableString: options.context.originalSource,
+    resolvedVariableString: options.context.value,
+  })
 
   if (wasOverridden) {
     fileRefEntry.wasOverridden = true
@@ -257,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))
@@ -411,7 +421,7 @@ ${JSON.stringify(options.context, null, 2)}`,
       if (fileExtension === 'toml' || fileExtension === 'tml') {
         valueToPopulate = JSON.stringify(TOML.parse(valueToPopulate))
       }
-      if (isIniLikeExtension(fileExtension)) {
+      if (isIniLikeExtension(fileExtension, relativePath)) {
         valueToPopulate = INI.toJson(valueToPopulate)
       }
       if (fileExtension === 'tf' || fileExtension === 'hcl') {
@@ -451,7 +461,7 @@ Please use ":" or "." to reference sub properties. ${deepPropertiesStr}`
       return Promise.resolve(valueToPopulate)
     }
 
-    if (isIniLikeExtension(fileExtension)) {
+    if (isIniLikeExtension(fileExtension, relativePath)) {
       valueToPopulate = INI.parse(valueToPopulate)
       return Promise.resolve(valueToPopulate)
     }

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) {

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()