command-runner.js

'use strict'

/* eslint-disable no-console, eslint-rules/eslint-process-env */

const fs = require('node:fs')
const path = require('path')
const { spawn, spawnSync } = require('child_process')

const {
  cleanupCommandOutputs,
  prepareCommandOutputs,
} = require('./command-output-policy')
const { getExecutableForSpawn } = require('./executable')
const {
  environmentNamesEqual,
  getEnvironmentValue,
  isDatadogEnvironmentName,
  mergeEnvironment,
  setEnvironmentValue,
} = require('./environment')
const { sanitizeConsoleText, sanitizeString } = require('./redaction')
const { ensureSafeDirectory, writeFileSafely } = require('./safe-files')

const INIT_PATH = path.resolve(__dirname, '..', 'init.js')
const REGISTER_PATH = path.resolve(__dirname, '..', '..', 'register.js')
const VALIDATION_MODE_ENV = '_DD_TEST_OPTIMIZATION_VALIDATION_MODE'
const VALIDATION_MANIFEST_ENV = '_DD_TEST_OPTIMIZATION_VALIDATION_MANIFEST_FILE'
const VALIDATION_OUTPUT_ENV = '_DD_TEST_OPTIMIZATION_VALIDATION_OUTPUT_DIR'
const VALIDATION_CAPTURE_MODE_ENV = '_DD_TEST_OPTIMIZATION_VALIDATION_CAPTURE_MODE'
const APM_AGENTLESS_ENV = '_DD_APM_TRACING_AGENTLESS_ENABLED'
const VALIDATION_RESERVED_ENV_NAMES = [
  'NODE_OPTIONS',
  VALIDATION_MANIFEST_ENV,
  VALIDATION_MODE_ENV,
  VALIDATION_OUTPUT_ENV,
  VALIDATION_CAPTURE_MODE_ENV,
  APM_AGENTLESS_ENV,
]
const CLEAN_ENV_ALLOWLIST = new Set([
  'COMSPEC',
  'ComSpec',
  'HOME',
  'LOGNAME',
  'PATH',
  'Path',
  'PATHEXT',
  'SHELL',
  'SystemRoot',
  'TEMP',
  'TMP',
  'TMPDIR',
  'USER',
  'USERNAME',
  'VOLTA_HOME',
  'WINDIR',
  'windir',
])
const VALIDATION_SUPPRESSION_ENV = {
  DD_AGENTLESS_LOG_SUBMISSION_ENABLED: 'false',
  DD_APPSEC_ENABLED: 'false',
  DD_CRASHTRACKING_ENABLED: 'false',
  DD_DATA_STREAMS_ENABLED: 'false',
  DD_DYNAMIC_INSTRUMENTATION_ENABLED: 'false',
  DD_EXPERIMENTAL_APPSEC_STANDALONE_ENABLED: 'false',
  DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED: 'false',
  DD_HEAP_SNAPSHOT_COUNT: '0',
  DD_IAST_ENABLED: 'false',
  DD_INSTRUMENTATION_TELEMETRY_ENABLED: 'false',
  DD_LLMOBS_ENABLED: 'false',
  DD_LOGS_OTEL_ENABLED: 'false',
  DD_METRICS_OTEL_ENABLED: 'false',
  DD_PROFILING_ENABLED: 'false',
  DD_REMOTE_CONFIGURATION_ENABLED: 'false',
  DD_RUNTIME_METRICS_ENABLED: 'false',
  DD_TRACE_OTEL_ENABLED: 'false',
  DD_TRACE_SPAN_LEAK_DEBUG: '0',
  // Offline validation only needs test-cycle events and explicitly configured filesystem inputs.
  DD_CIVISIBILITY_GIT_UPLOAD_ENABLED: 'false',
  DD_CIVISIBILITY_GIT_UNSHALLOW_ENABLED: 'false',
  DD_CIVISIBILITY_IMPACTED_TESTS_DETECTION_ENABLED: 'false',
  DD_EXPERIMENTAL_TEST_REQUESTS_FS_CACHE: 'false',
  DD_TEST_FAILED_TEST_REPLAY_ENABLED: 'false',
}
const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024
const EARLY_STOP_KILL_GRACE_MS = 500
const TIMEOUT_KILL_GRACE_MS = 5000
const TIMEOUT_FINALIZE_GRACE_MS = 1000
const WINDOWS_TASKKILL_TIMEOUT_MS = 10_000

function runCommand (command, options = {}) {
  const {
    env = {},
    envMode = 'inherit',
    outDir,
    label,
    repositoryRoot,
    requireExecutableApproval = false,
    stopWhen,
    verbose = false,
  } = options
  const artifactRoot = options.artifactRoot || path.dirname(outDir)
  const startedAt = Date.now()
  const {
    maxOutputBytes,
    timeoutFinalizeGraceMs,
    timeoutKillGraceMs,
    timeoutMs,
  } = getCommandExecutionSettings(command)
  const result = {
    label,
    command: serializeCommand(command),
    displayCommand: serializeDisplayCommand(command),
    commandDetails: getCommandDetails(command),
    cwd: command.cwd,
    exitCode: null,
    signal: null,
    stoppedEarly: false,
    durationMs: 0,
    timedOut: false,
    stdout: '',
    stdoutOmittedBytes: 0,
    stdoutTruncated: false,
    stderr: '',
    stderrOmittedBytes: 0,
    stderrTruncated: false,
    artifacts: {},
  }

  ensureSafeDirectory(artifactRoot, outDir, 'command artifact directory')
  try {
    assertNoInlineValidationEnvOverrides(command, env)
  } catch (error) {
    return Promise.reject(error)
  }
  const missingRequiredEnvVars = getMissingRequiredEnvironmentNames(command.requiredEnvVars)
  if (missingRequiredEnvVars.length > 0) {
    result.missingRequiredEnvVars = missingRequiredEnvVars
    result.stderr = 'The approved command requires environment variables that are not available: ' +
      `${missingRequiredEnvVars.join(', ')}.\n`
    result.durationMs = Date.now() - startedAt
    return Promise.resolve(result)
  }
  const outputStates = prepareCommandOutputs({ command, artifactRoot, outDir, repositoryRoot })

  return new Promise((resolve) => {
    let finalized = false
    let processTreeCleanupPending = false
    let pendingCloseResult
    const childEnv = { ...getBaseEnv(envMode, command.requiredEnvVars) }
    mergeEnvironment(childEnv, command.env)
    mergeEnvironment(childEnv, env)
    const commandNodeOptions = getEnvironmentValue(command.env || {}, 'NODE_OPTIONS')
    const injectedNodeOptions = getEnvironmentValue(env, 'NODE_OPTIONS')
    if (commandNodeOptions && injectedNodeOptions) {
      setEnvironmentValue(childEnv, 'NODE_OPTIONS', mergeNodeOptions(injectedNodeOptions, commandNodeOptions))
    }
    for (const [name, value] of Object.entries(childEnv)) {
      if (value === undefined) delete childEnv[name]
    }

    const useProcessGroup = shouldUseProcessGroup()
    const windowsTaskkillPath = getWindowsTaskkillPath()
    if (process.platform === 'win32' && !windowsTaskkillPath) {
      result.stderr = 'Validation cannot safely bound test processes because the Windows process-tree cleanup ' +
        'executable is unavailable.\n'
      result.durationMs = Date.now() - startedAt
      try {
        finishCommandOutputCleanup(result, outputStates)
      } catch (cleanupError) {
        result.outputCleanupError = cleanupError?.message || String(cleanupError)
      }
      resolve(result)
      return
    }
    const managesProcessTree = useProcessGroup || Boolean(windowsTaskkillPath)
    let child
    try {
      const executable = getExecutableForSpawn(command, { requireApproval: requireExecutableApproval })
      const argv0 = process.platform === 'win32' ? {} : { argv0: executable.argv0 }
      child = spawn(executable.path, command.argv.slice(1), {
        ...argv0,
        cwd: command.cwd,
        detached: useProcessGroup,
        env: childEnv,
        shell: false,
        stdio: ['ignore', 'pipe', 'pipe'],
      })
    } catch (error) {
      result.stderr = `${error.stack || error}\n`
      result.durationMs = Date.now() - startedAt
      try {
        finishCommandOutputCleanup(result, outputStates)
      } catch (cleanupError) {
        result.outputCleanupError = cleanupError?.message || String(cleanupError)
      }
      resolve(result)
      return
    }

    if (verbose) {
      console.log(sanitizeConsoleText(
        `[test-optimization-validator] running ${label || serializeCommand(command)}`
      ))
    }

    let killTimer
    let finalizeTimer
    let stopTimer
    let stdoutCapture
    let stderrCapture
    const timeout = setTimeout(() => {
      result.timedOut = true
      processTreeCleanupPending = managesProcessTree
      signalChild(child, 'SIGTERM', useProcessGroup, windowsTaskkillPath)
      killTimer = setTimeout(() => {
        signalChild(child, 'SIGKILL', useProcessGroup, windowsTaskkillPath)
        finishProcessTreeCleanup('SIGKILL')
      }, timeoutKillGraceMs)
    }, timeoutMs)

    if (stopWhen) {
      stopTimer = setInterval(() => {
        let shouldStop = false
        try {
          shouldStop = stopWhen()
        } catch {}
        if (!shouldStop) return

        clearInterval(stopTimer)
        result.stoppedEarly = true
        processTreeCleanupPending = managesProcessTree
        signalChild(child, 'SIGTERM', useProcessGroup, windowsTaskkillPath)
        killTimer = setTimeout(() => {
          signalChild(child, 'SIGKILL', useProcessGroup, windowsTaskkillPath)
          finishProcessTreeCleanup('SIGKILL')
        }, EARLY_STOP_KILL_GRACE_MS)
      }, 25)
    }

    child.stdout.on('data', chunk => {
      const capture = appendCapturedOutput(stdoutCapture, chunk, maxOutputBytes)
      stdoutCapture = capture
      result.stdout = capture.output
      result.stdoutOmittedBytes = capture.omittedBytes
      result.stdoutTruncated = capture.truncated
    })
    child.stderr.on('data', chunk => {
      const capture = appendCapturedOutput(stderrCapture, chunk, maxOutputBytes)
      stderrCapture = capture
      result.stderr = capture.output
      result.stderrOmittedBytes = capture.omittedBytes
      result.stderrTruncated = capture.truncated
    })
    child.on('error', err => {
      result.stderr += `${err.stack || err}\n`
      finalize(null, null)
    })
    child.on('close', (code, signal) => {
      if (processTreeCleanupPending) {
        pendingCloseResult = { code, signal }
        signalChild(child, 'SIGKILL', useProcessGroup, windowsTaskkillPath)
        finishProcessTreeCleanup(signal)
        return
      }
      finalize(code, signal)
    })

    function finishProcessTreeCleanup (fallbackSignal) {
      processTreeCleanupPending = false
      if (pendingCloseResult) {
        finalize(pendingCloseResult.code, pendingCloseResult.signal || fallbackSignal)
        return
      }
      finalizeTimer = setTimeout(() => finalize(null, fallbackSignal), timeoutFinalizeGraceMs)
    }

    function finalize (code, signal) {
      if (finalized) return
      finalized = true
      clearTimeout(timeout)
      clearTimeout(killTimer)
      clearTimeout(finalizeTimer)
      clearInterval(stopTimer)
      result.exitCode = code
      result.signal = signal
      result.durationMs = Date.now() - startedAt

      try {
        finishCommandOutputCleanup(result, outputStates)
      } catch (err) {
        result.outputCleanupError = err && err.message ? err.message : String(err)
        result.stderr += '\n[test-optimization-validator] could not clean up command outputs: ' +
          `${result.outputCleanupError}\n`
        if (result.exitCode === 0) result.exitCode = 1
      }

      result.artifacts.stdout = path.join(outDir, 'stdout.txt')
      result.artifacts.stderr = path.join(outDir, 'stderr.txt')
      result.artifacts.command = path.join(outDir, 'command.json')

      try {
        writeFileSafely(
          artifactRoot,
          result.artifacts.stdout,
          sanitizeString(result.stdout),
          'command stdout artifact'
        )
        writeFileSafely(
          artifactRoot,
          result.artifacts.stderr,
          sanitizeString(result.stderr),
          'command stderr artifact'
        )
        writeFileSafely(artifactRoot, result.artifacts.command, `${JSON.stringify({
          command: sanitizeString(result.command),
          displayCommand: sanitizeString(result.displayCommand),
          commandDetails: result.commandDetails,
          cwd: result.cwd,
          exitCode: result.exitCode,
          signal: result.signal,
          durationMs: result.durationMs,
          timedOut: result.timedOut,
          stoppedEarly: result.stoppedEarly,
          stdoutTruncated: result.stdoutTruncated,
          stdoutOmittedBytes: result.stdoutOmittedBytes,
          stderrTruncated: result.stderrTruncated,
          stderrOmittedBytes: result.stderrOmittedBytes,
          maxOutputBytes,
          commandOutputPaths: result.commandOutputPaths,
          outputCleanupError: result.outputCleanupError,
        }, null, 2)}\n`, 'command metadata artifact')
      } catch (error) {
        result.artifactWriteError = error?.message || String(error)
        result.stderr += '\n[test-optimization-validator] could not write command artifacts: ' +
          `${result.artifactWriteError}\n`
        if (!Number.isInteger(result.exitCode) || result.exitCode === 0) result.exitCode = 1
      }

      resolve(result)
    }
  })
}

/**
 * Cleans command outputs after the command exits.
 *
 * @param {object} result command result
 * @param {object[]} outputStates prepared command output state
 * @returns {void}
 */
function finishCommandOutputCleanup (result, outputStates) {
  result.commandOutputPaths = cleanupCommandOutputs(outputStates)
}

/**
 * Returns the effective bounded execution settings used for one project command.
 *
 * @param {object} command structured command
 * @returns {{maxOutputBytes: number, timeoutFinalizeGraceMs: number, timeoutKillGraceMs: number, timeoutMs: number}}
 * execution settings
 */
function getCommandExecutionSettings (command) {
  return {
    maxOutputBytes: command.maxOutputBytes || DEFAULT_MAX_OUTPUT_BYTES,
    timeoutFinalizeGraceMs: command.timeoutFinalizeGraceMs || TIMEOUT_FINALIZE_GRACE_MS,
    timeoutKillGraceMs: command.timeoutKillGraceMs || TIMEOUT_KILL_GRACE_MS,
    timeoutMs: command.timeoutMs || 300_000,
  }
}

/**
 * Appends output while retaining only the latest bytes for diagnostic artifacts.
 *
 * @param {object|undefined} current currently captured output state
 * @param {Buffer|string} chunk new output chunk
 * @param {number} maxBytes maximum retained bytes
 * @returns {{output: string, truncated: boolean}} retained output and truncation flag
 */
function appendCapturedOutput (current, chunk, maxBytes) {
  const nextChunk = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))
  const totalBytes = (current?.totalBytes || 0) + nextChunk.length
  const headLimit = Math.floor(maxBytes / 2)
  const tailLimit = maxBytes - headLimit
  let head = current?.head || Buffer.alloc(0)
  let tail

  if (current?.truncated) {
    const combinedTail = Buffer.concat([current.tail, nextChunk])
    tail = combinedTail.subarray(Math.max(0, combinedTail.length - tailLimit))
  } else {
    const combined = Buffer.concat([current?.tail || Buffer.alloc(0), nextChunk])
    if (combined.length <= maxBytes) {
      return {
        head,
        tail: combined,
        totalBytes,
        omittedBytes: 0,
        output: combined.toString('utf8'),
        truncated: false,
      }
    }
    head = combined.subarray(0, headLimit)
    tail = combined.subarray(combined.length - tailLimit)
  }

  const omittedBytes = totalBytes - head.length - tail.length
  return {
    head,
    tail,
    totalBytes,
    omittedBytes,
    output: `${head.toString('utf8')}\n[test-optimization-validator] ${omittedBytes} bytes omitted\n` +
      tail.toString('utf8'),
    truncated: true,
  }
}

function shouldUseProcessGroup () {
  return process.platform !== 'win32'
}

/**
 * Resolves the fixed Windows process-tree cleanup executable without PATH lookup.
 *
 * @returns {string|undefined} physical taskkill executable
 */
function getWindowsTaskkillPath () {
  if (process.platform !== 'win32') return

  const systemRoot = getEnvironmentValue(process.env, 'SystemRoot') ||
    getEnvironmentValue(process.env, 'WINDIR')
  if (!systemRoot || !path.win32.isAbsolute(systemRoot)) return

  try {
    const root = fs.realpathSync(systemRoot)
    const candidate = path.win32.join(root, 'System32', 'taskkill.exe')
    const stat = fs.lstatSync(candidate)
    const physical = fs.realpathSync(candidate)
    const relative = path.win32.relative(root, physical)
    if (!stat.isFile() || stat.isSymbolicLink() ||
      relative.startsWith('..') || path.win32.isAbsolute(relative)) return
    return physical
  } catch {}
}

function signalChild (child, signal, useProcessGroup, windowsTaskkillPath) {
  if (windowsTaskkillPath) {
    try {
      const args = ['/PID', String(child.pid), '/T', '/F']
      const outcome = spawnSync(windowsTaskkillPath, args, {
        shell: false,
        stdio: 'ignore',
        timeout: WINDOWS_TASKKILL_TIMEOUT_MS,
        windowsHide: true,
      })
      if (!outcome.error && outcome.status === 0) return
    } catch {}
  }

  try {
    if (useProcessGroup) {
      process.kill(-child.pid, signal)
      return
    }
  } catch {}

  child.kill(signal)
}

function getBaseEnv (envMode, requiredEnvVars = []) {
  if (envMode !== 'clean') return process.env

  const cleanEnv = {}
  for (const name of [...CLEAN_ENV_ALLOWLIST, ...requiredEnvVars]) {
    const entry = Object.entries(process.env).find(([candidate]) => {
      return environmentNamesEqual(candidate, name)
    })
    if (entry) setEnvironmentValue(cleanEnv, name, entry[1])
  }
  return cleanEnv
}

/**
 * Finds explicitly approved ambient variables that are unavailable at execution time.
 *
 * @param {string[]|undefined} requiredEnvVars approved variable names
 * @returns {string[]} missing names
 */
function getMissingRequiredEnvironmentNames (requiredEnvVars = []) {
  return requiredEnvVars.filter(name => getEnvironmentValue(process.env, name) === undefined)
}

function buildDatadogEnv ({ fixture, outputRoot, scenario, framework }) {
  const offline = buildOfflineValidationEnv({ fixture, outputRoot })
  return {
    ...offline,
    DD_CIVISIBILITY_AGENTLESS_ENABLED: '0',
    DD_CIVISIBILITY_ENABLED: '1',
    DD_TRACE_ENABLED: 'true',
    ...VALIDATION_SUPPRESSION_ENV,
    DD_SERVICE: 'dd-test-optimization-validation',
    DD_ENV: 'local-validation',
    DD_CIVISIBILITY_FLAKY_RETRY_COUNT: '2',
    DD_TAGS: `test_optimization.validation.scenario:${scenario}`,
    NODE_OPTIONS: withCiPreloads('', framework),
  }
}

function buildOfflineCaptureEnv ({ fixture, outputRoot }) {
  return {
    ...buildOfflineValidationEnv({ fixture, outputRoot }),
    [VALIDATION_CAPTURE_MODE_ENV]: 'sample',
    DD_TRACE_DEBUG: '1',
    DD_TRACE_LOG_LEVEL: 'debug',
    ...VALIDATION_SUPPRESSION_ENV,
  }
}

/**
 * Builds the private environment used by the filesystem-only validation exporter.
 *
 * @param {object} input offline validation inputs
 * @param {{manifestPath: string}} input.fixture authoritative cache fixture
 * @param {string} input.outputRoot pre-created payload output root
 * @returns {NodeJS.ProcessEnv} validation transport environment
 */
function buildOfflineValidationEnv ({ fixture, outputRoot }) {
  return {
    DD_AGENT_HOST: undefined,
    DD_API_KEY: undefined,
    DD_APP_KEY: undefined,
    DATADOG_API_KEY: undefined,
    [APM_AGENTLESS_ENV]: undefined,
    DD_CIVISIBILITY_AGENTLESS_ENABLED: '0',
    DD_CIVISIBILITY_AGENTLESS_URL: undefined,
    DD_EXPERIMENTAL_TEST_OPT_SETTINGS_CACHE: undefined,
    DD_TRACE_AGENT_HOSTNAME: undefined,
    DD_TRACE_AGENT_PORT: undefined,
    DD_TRACE_AGENT_UNIX_DOMAIN_SOCKET: undefined,
    DD_TRACE_AGENT_URL: undefined,
    OTEL_LOGS_EXPORTER: undefined,
    OTEL_METRICS_EXPORTER: undefined,
    OTEL_TRACES_EXPORTER: undefined,
    [VALIDATION_MANIFEST_ENV]: fixture.manifestPath,
    [VALIDATION_MODE_ENV]: '1',
    [VALIDATION_OUTPUT_ENV]: outputRoot,
  }
}

/**
 * Rejects command-local assignments that can bypass validator-controlled offline routing.
 *
 * @param {object} command command to execute
 * @param {NodeJS.ProcessEnv} env validator environment overrides
 */
function assertNoInlineValidationEnvOverrides (command, env) {
  if (!env[VALIDATION_MODE_ENV]) return
  if (command.env) {
    for (const name of Object.keys(command.env)) {
      const normalized = process.platform === 'win32' ? name.toUpperCase() : name
      if (VALIDATION_RESERVED_ENV_NAMES.some(reserved => environmentNamesEqual(reserved, name)) ||
        isDatadogEnvironmentName(name) || normalized.startsWith('OTEL_')) {
        throw new Error(`Direct-runner adapter must not override validator-controlled environment variable ${name}.`)
      }
    }
  }
}

function withCiPreloads (nodeOptions = '', framework) {
  let result = nodeOptions.trim()

  if (framework?.framework === 'vitest' && !hasRegister(result)) {
    result = `--import ${formatNodeRequire(REGISTER_PATH)}${result ? ` ${result}` : ''}`
  }

  if (!hasCiInit(result)) {
    result = `${result ? `${result} ` : ''}-r ${formatNodeRequire(INIT_PATH)}`
  }

  return result
}

function mergeNodeOptions (...nodeOptions) {
  return nodeOptions
    .map(value => String(value || '').trim())
    .filter(Boolean)
    .join(' ')
}

function hasCiInit (nodeOptions) {
  return nodeOptions.includes('dd-trace/ci/init') || nodeOptions.includes(INIT_PATH)
}

function hasRegister (nodeOptions) {
  return nodeOptions.includes('dd-trace/register.js') || nodeOptions.includes(REGISTER_PATH)
}

function formatNodeRequire (filename) {
  if (!/\s/.test(filename)) return filename
  return JSON.stringify(filename)
}

function serializeCommand (command) {
  return command.argv.join(' ')
}

/**
 * Renders the command that will actually execute without trusting display-only manifest fields.
 *
 * @param {object} command command to render
 * @returns {string} unambiguous customer-facing command
 */
function serializeApprovalCommand (command) {
  return command.argv.map(formatApprovalArgument).join(' ')
}

/**
 * Quotes arguments whose boundaries would otherwise be ambiguous in an approval plan.
 *
 * @param {string} value argument value
 * @returns {string} visible argument
 */
function formatApprovalArgument (value) {
  const argument = String(value)
  if (/^[A-Za-z0-9_@%+=:,./\\-]+$/.test(argument)) return argument
  if (process.platform === 'win32') return JSON.stringify(argument)
  return `'${argument.replaceAll('\'', '\'"\'"\'')}'`
}

function serializeDisplayCommand (command) {
  return command.argv.join(' ')
}

function getCommandDetails (command) {
  return {
    executionBoundary: 'validator-owned-direct-runner',
    runner: command.argv[1],
  }
}

module.exports = {
  runCommand,
  buildOfflineCaptureEnv,
  buildDatadogEnv,
  getBaseEnv,
  getCommandDetails,
  getCommandExecutionSettings,
  serializeApprovalCommand,
  serializeCommand,
  serializeDisplayCommand,
  withCiPreloads,
  mergeNodeOptions,
}