@gefyra/complies-with-eu 1.2.0 → 1.3.1

package/src/lib/javaValidator.js

@@ -7,6 +7,12 @@ const chalk = require('chalk');
 const { getValidatorJar, loadValidatorParams } = require('./config');
 const { getJavaCommand } = require('./javaCheck');
 const { track } = require('./processRegistry');
+const {
+  createOutputHandler,
+  createProgress,
+  extractResultInfo,
+  createValidatorError,
+} = require('./validatorOutput');
 
 /**
  * Runs `fn` over `items` with at most `limit` concurrent calls and returns
@@ -29,12 +35,18 @@ async function mapSettled(items, limit, fn) {
   return results;
 }
 
+// "*FAILURE*: ...", "*SUCCESS*: ..." or "Success: ..." (validator 7.x prints the
+// success summary without asterisks). Anchored at column 0, so issue lines
+// (indented) never match.
+const SUMMARY_LINE = /^\*?(FAILURE|SUCCESS)\*?:\s*(.+)/i;
+
 /**
  * Parses the Java Validator console output into structured issues.
  *
  * Expected line formats:
  *   *FAILURE*: 6 errors, 18 warnings, 12 notes
- *   *SUCCESS*: ...
+ *   *SUCCESS*: ...           (older validators)
+ *   Success: 0 errors, ...   (validator 7.x when there are no errors)
  *     Severity @ Location (line X, colY): Message {MSG_ID}
  *     Severity @ Location: Message {MSG_ID}
  *       sub-detail line
@@ -50,9 +62,9 @@ function parseValidatorOutput(output) {
 
   for (const line of lines) {
     // Summary line
-    const summaryMatch = line.match(/^\*(FAILURE|SUCCESS)\*:\s*(.+)/);
+    const summaryMatch = line.match(SUMMARY_LINE);
     if (summaryMatch) {
-      summary = { result: summaryMatch[1], text: summaryMatch[2].trim() };
+      summary = { result: summaryMatch[1].toUpperCase(), text: summaryMatch[2].trim() };
       currentIssue = null;
       continue;
     }
@@ -163,23 +175,39 @@ function parseValidatorOutputBatch(output) {
 }
 
 /**
- * Spawns the Java validator and collects its combined output. All child output
- * is mirrored to stderr (never stdout, which is reserved for --json output).
+ * Normalises the legacy boolean `debug` argument or an options object into
+ * { debug, verbose }. --debug implies verbose output.
+ */
+function normalizeRunOptions(opts) {
+  const o = (opts && typeof opts === 'object') ? opts : { debug: !!opts };
+  const debug = !!o.debug;
+  return { ...o, debug, verbose: debug || !!o.verbose };
+}
+
+/**
+ * Spawns the Java validator and collects its combined output. The output is
+ * mirrored only with `verbose` (to stderr, never to stdout, which is reserved
+ * for --json output); otherwise only phase hints are reported via `onPhase`.
  *
- * @returns {Promise<{ code: number|null, rawOutput: string }>}
+ * @param {string[]} args
+ * @param {object}   [opts]
+ * @param {boolean}  [opts.verbose]  - Stream the raw output
+ * @param {Function} [opts.onPhase]  - Phase hint callback (see validatorOutput.createOutputHandler)
+ * @param {Function} [opts.onChunk]  - Called with every raw output chunk
+ * @param {Function} [opts.write]    - Sink for mirrored output (default: stderr)
+ * @param {Function} [opts.spawnFn]  - Replacement for child_process.spawn (tests)
+ * @returns {Promise<{ code: number|null, signal: string|null, rawOutput: string }>}
  */
-function spawnValidator(args) {
+function spawnValidator(args, { verbose = false, onPhase, onChunk, write, spawnFn = spawn } = {}) {
   return new Promise((resolve, reject) => {
-    const outputChunks = [];
-    const proc = track(spawn(getJavaCommand(), args, { windowsHide: true }));
-    const onData = (data) => {
-      const text = data.toString();
-      process.stderr.write(chalk.gray(text));
-      outputChunks.push(text);
-    };
-    proc.stdout.on('data', onData);
-    proc.stderr.on('data', onData);
-    proc.on('close', (code) => resolve({ code, rawOutput: outputChunks.join('') }));
+    const handler = createOutputHandler({ verbose, write, onPhase, onChunk });
+    const proc = track(spawnFn(getJavaCommand(), args, { windowsHide: true }));
+    proc.stdout.on('data', handler.onData);
+    proc.stderr.on('data', handler.onData);
+    proc.on('close', (code, signal) => {
+      handler.flush();
+      resolve({ code, signal: signal || null, rawOutput: handler.getOutput() });
+    });
     proc.on('error', (err) => reject(new Error(`Could not start Java for the FHIR validator: ${err.message}`)));
   });
 }
@@ -202,72 +230,125 @@ function printCommand(args, debug, label, igCount) {
   }
 }
 
+/**
+ * Runs the validator with concise progress (or streamed output with `verbose`),
+ * always writes the raw output to `logPath`, and rejects with an understandable
+ * error (exit code, output tail, log path) when `hasResult` says the output
+ * contains no usable result.
+ *
+ * @param {object}   p
+ * @param {string[]} p.args
+ * @param {string}   p.logPath
+ * @param {Function} p.hasResult      - (rawOutput) => boolean
+ * @param {boolean}  [p.batch]        - Describe the result as a number of file results
+ * @param {boolean}  [p.verbose]
+ * @param {NodeJS.WritableStream} [p.stream] - Progress/output stream (default stderr)
+ * @param {Function} [p.spawnFn]      - Replacement for child_process.spawn (tests)
+ * @returns {Promise<{ code: number|null, rawOutput: string, logPath: string }>}
+ */
+async function executeValidator({ args, logPath, hasResult, batch = false, verbose = false, stream = process.stderr, spawnFn }) {
+  const progress = createProgress({ text: 'Running HL7 FHIR Validator', verbose, stream });
+  let result;
+  try {
+    result = await spawnValidator(args, {
+      verbose,
+      spawnFn,
+      write: (text) => stream.write(chalk.gray(text)),
+      onPhase: (label) => progress.phase(label),
+    });
+  } catch (err) {
+    progress.fail('HL7 FHIR Validator could not be started');
+    throw err;
+  }
+
+  const { code, signal, rawOutput } = result;
+  // Written after the run (not streamed): in batch mode the log lives inside the
+  // directory being validated and must not exist while the validator scans it.
+  let logWritten = true;
+  try {
+    await fs.outputFile(logPath, rawOutput, 'utf8');
+  } catch {
+    logWritten = false; // best effort; never fail the run because of the log
+  }
+  const shownLog = logWritten ? logPath : null;
+  if (!hasResult(rawOutput)) {
+    progress.fail(signal
+      ? `HL7 FHIR Validator was terminated (${signal})`
+      : `HL7 FHIR Validator failed (exit code ${code}, no result summary)`);
+    throw createValidatorError({ reason: 'produced no result summary', code, signal, rawOutput, logPath: shownLog });
+  }
+
+  const { summaryLine, doneLine, summaryCount } = extractResultInfo(rawOutput);
+  progress.succeed(batch
+    ? `HL7 FHIR Validator finished: ${summaryCount} file result(s)`
+    : `HL7 FHIR Validator finished: ${summaryLine}`);
+  if (doneLine) stream.write(chalk.gray(`  ${doneLine}\n`));
+  if (shownLog) stream.write(chalk.gray(`  Raw validator output: ${shownLog}\n`));
+  return { code, rawOutput, logPath: shownLog };
+}
+
 /**
  * Runs the FHIR Java Validator against a resource file.
  * Does NOT use -output / -html-output; parses the console output instead.
+ * The raw output is always written to "<resource>-raw.log" next to the file.
  *
  * Rejects when the validator produced no result summary (crash, wrong Java,
  * unknown option, ...): a missing summary must never be read as "no issues".
  *
  * @param {string}   resourceFile - Path to the resource/profile JSON to validate
  * @param {string[]} igIds        - List of name#version identifiers for -ig
- * @param {boolean}  debug        - Print the full command before execution
+ * @param {boolean|{debug?: boolean, verbose?: boolean}} [opts] - Legacy debug flag or options
  * @param {string[]} extraArgs    - Additional arguments appended after base params (e.g. ['-resolve-path', dir])
- * @returns {Promise<{rawOutput: string, parsed: object, mode: 'local'}>}
+ * @returns {Promise<{rawOutput: string, parsed: object, mode: 'local', logPath: string}>}
  */
-async function runValidator(resourceFile, igIds, debug = false, extraArgs = []) {
-
+async function runValidator(resourceFile, igIds, opts = false, extraArgs = []) {
+  const { debug, verbose } = normalizeRunOptions(opts);
   const args = await buildLocalArgs(resourceFile, igIds, extraArgs);
   printCommand(args, debug, '', igIds.length);
 
-  const { code, rawOutput } = await spawnValidator(args);
-  const parsed = parseValidatorOutput(rawOutput);
   const logPath = resourceFile.replace(/\.json$/, '') + '-raw.log';
-  if (debug || !parsed.summary) {
-    await fs.outputFile(logPath, rawOutput, 'utf8');
-    if (debug) process.stderr.write(chalk.bold.yellow(`\n[DEBUG] Raw validator output written to: ${logPath}\n`));
-  }
-  if (!parsed.summary) {
-    throw new Error(
-      `FHIR Java Validator exited with code ${code} and produced no result summary. ` +
-      `Raw output: ${logPath}`
-    );
-  }
-  return { rawOutput, parsed, mode: 'local' };
+  const { rawOutput } = await executeValidator({
+    args,
+    logPath,
+    verbose,
+    hasResult: (out) => !!parseValidatorOutput(out).summary,
+  });
+  return { rawOutput, parsed: parseValidatorOutput(rawOutput), mode: 'local', logPath };
 }
 
 /**
  * Runs the FHIR Java Validator against an entire directory in one invocation.
- * Parses per-file sections from the combined output.
+ * Parses per-file sections from the combined output. The raw output is always
+ * written to "<dir>/_batch-raw.log".
  *
  * @param {string}   dirPath   - Directory containing the resource files to validate
  * @param {string[]} igIds     - List of name#version identifiers for -ig
- * @param {boolean}  debug     - Print the full command and write raw log
+ * @param {boolean|{debug?: boolean, verbose?: boolean}} [opts] - Legacy debug flag or options
  * @param {string[]} extraArgs - Additional arguments appended after base params
- * @returns {Promise<{rawOutput: string, results: Array<{fileName, summary, issues}>}>}
+ * @returns {Promise<{rawOutput: string, results: Array<{fileName, summary, issues}>, logPath: string}>}
  */
-async function runValidatorBatch(dirPath, igIds, debug = false, extraArgs = []) {
-
+async function runValidatorBatch(dirPath, igIds, opts = false, extraArgs = []) {
+  const { debug, verbose } = normalizeRunOptions(opts);
   const args = await buildLocalArgs(dirPath, igIds, extraArgs);
   printCommand(args, debug, ' (batch)', igIds.length);
 
-  const { code, rawOutput } = await spawnValidator(args);
-  const results = parseValidatorOutputBatch(rawOutput);
   const logPath = path.join(dirPath, '_batch-raw.log');
-  const noResults = !results.some(r => r.summary);
-  if (debug || noResults) {
-    await fs.outputFile(logPath, rawOutput, 'utf8');
-    if (debug) process.stderr.write(chalk.bold.yellow(`\n[DEBUG] Raw validator output written to: ${logPath}\n`));
-  }
-  if (noResults) {
-    throw new Error(`FHIR Java Validator exited with code ${code} and produced no result summary. Raw output: ${logPath}`);
-  }
-  return { rawOutput, results };
+  const { rawOutput } = await executeValidator({
+    args,
+    logPath,
+    verbose,
+    batch: true,
+    hasResult: (out) => parseValidatorOutputBatch(out).some(r => r.summary),
+  });
+  return { rawOutput, results: parseValidatorOutputBatch(rawOutput), logPath };
 }
 
 module.exports = {
   runValidator,
   runValidatorBatch,
+  executeValidator,
+  spawnValidator,
+  normalizeRunOptions,
   parseValidatorOutput,
   parseValidatorOutputBatch,
   mapSettled,

package/src/lib/javaValidatorServer.js

@@ -10,12 +10,15 @@ const { getValidatorJar, loadValidatorParams } = require('./config');
 const { getJavaCommand } = require('./javaCheck');
 const { track } = require('./processRegistry');
 const { mapSettled } = require('./javaValidator');
+const { createOutputHandler, createProgress, formatValidatorError, formatValidatorErrorShort, createValidatorError, tailLines } = require('./validatorOutput');
 
 const DEFAULT_PORT = 7272;
 const READY_POLL_INTERVAL_MS = 2500;
 // Total budget: port open + lazy IG loading + possible network timeouts on first request
 const READY_TIMEOUT_MS = 600_000; // 10 min
 const POST_CONCURRENCY = 4;
+// In-memory tail of the server output kept for error messages (the full output goes to the log file)
+const SERVER_OUTPUT_TAIL_CHARS = 64 * 1024;
 // Text of the validator message SD_EXTENSION_COMPLIES_WITH_ERROR
 const COMPLIES_WITH_ERROR_TEXT = /does not comply with claimed profile '[^']+'/;
 
@@ -70,11 +73,11 @@ async function serverHasCanonical(port, canonical) {
  * Phase 1: polls until the port accepts connections.
  * Throws if `isDead()` returns true (process exited).
  */
-async function waitForPort(port, deadline, isDead) {
+async function waitForPort(port, deadline, isDead, pollIntervalMs = READY_POLL_INTERVAL_MS) {
   while (Date.now() < deadline) {
     if (isDead()) throw new Error('Validator process exited before the server became ready');
     if (await isServerReady(port)) return;
-    await new Promise(r => setTimeout(r, READY_POLL_INTERVAL_MS));
+    await new Promise(r => setTimeout(r, Math.max(0, Math.min(pollIntervalMs, deadline - Date.now()))));
   }
   throw new Error(`Validator server on port ${port} did not start within the timeout`);
 }
@@ -115,46 +118,98 @@ async function warmupServer(port, deadline, isDead) {
  * Waits until the server is truly ready (lazy loading complete) before returning.
  * The JVM is killed if startup or warmup fails, and when the CLI exits.
  *
+ * The server output is written to `logFile` (when given) and streamed to stderr
+ * only with `verbose`/`debug`; otherwise a concise progress indicator is shown.
+ * Startup failures include the last lines of server output and the log path.
+ *
  * @param {object}   opts
- * @param {string[]} opts.igIds  - IG identifiers (name#version or local path) to pre-load
- * @param {number}  [opts.port]  - Port to listen on (default: a free port chosen by the OS)
- * @param {boolean} [opts.debug] - Print the full startup command
- * @returns {Promise<{ port: number, stop: Function }>}
+ * @param {string[]} opts.igIds    - IG identifiers (name#version or local path) to pre-load
+ * @param {number}  [opts.port]    - Port to listen on (default: a free port chosen by the OS)
+ * @param {boolean} [opts.debug]   - Print the full startup command (implies verbose)
+ * @param {boolean} [opts.verbose] - Stream the full server output to stderr
+ * @param {string}  [opts.logFile] - File that receives the raw server output
+ * @param {NodeJS.WritableStream} [opts.stream] - Progress / output sink (default process.stderr)
+ * @param {Function} [opts.spawnFn]  - child_process.spawn replacement (tests)
+ * @param {string}  [opts.jar]       - validator_cli.jar path (default: the installed one)
+ * @param {number}  [opts.readyTimeoutMs] - Startup + warmup budget (default 10 min)
+ * @param {number}  [opts.pollIntervalMs] - Port poll interval
+ * @param {number}  [opts.startupGraceMs] - Pause that catches immediate start failures
+ * @returns {Promise<{ port: number, stop: Function, logFile: string|null,
+ *   isDead: Function, exitInfo: Function, getOutput: Function, tail: Function }>}
+ *   `isDead()` / `exitInfo()` tell whether (and how) the JVM exited after startup,
+ *   `getOutput()` returns the in-memory tail of its output, `tail(n)` its last n lines.
  */
-async function startValidatorServer({ igIds, port = null, debug = false }) {
-  const jar = getValidatorJar();
+async function startValidatorServer({
+  igIds,
+  port = null,
+  debug = false,
+  verbose = false,
+  logFile = null,
+  stream = process.stderr,
+  spawnFn = spawn,
+  jar = getValidatorJar(),
+  readyTimeoutMs = READY_TIMEOUT_MS,
+  pollIntervalMs = READY_POLL_INTERVAL_MS,
+  startupGraceMs = 600,
+}) {
   if (!await fs.pathExists(jar)) {
     throw new Error(`validator_cli.jar not found at ${jar}. Run: complies-with-eu init`);
   }
   const listenPort = port || await findFreePort();
+  const showOutput = debug || verbose;
 
   const baseParams = loadValidatorParams();
   const igArgs = igIds.flatMap(id => ['-ig', id]);
 
   const args = [
     '-jar', jar,
-    '-server', String(listenPort),
+    'server', String(listenPort),
     ...igArgs,
     ...baseParams,
   ];
 
+  const write = (text) => stream.write(text);
   if (debug) {
-    process.stderr.write(chalk.bold.yellow('\n[DEBUG] Starting validator server:\n'));
-    process.stderr.write(chalk.yellow(`${getJavaCommand()} ${args.join(' ')}\n\n`));
+    write(chalk.bold.yellow('\n[DEBUG] Starting validator server:\n'));
+    write(chalk.yellow(`${getJavaCommand()} ${args.join(' ')}\n\n`));
   } else {
-    process.stderr.write(chalk.gray(`  java -jar validator_cli.jar -server ${listenPort} ... (${igIds.length} IGs)\n`));
+    write(chalk.gray(`  java -jar validator_cli.jar server ${listenPort} ... (${igIds.length} IGs)\n`));
+  }
+
+  let logStream = null;
+  if (logFile) {
+    await fs.ensureDir(path.dirname(logFile));
+    logStream = fs.createWriteStream(logFile, { encoding: 'utf8' });
+    logStream.on('error', () => { /* the log is best effort */ });
   }
 
-  const proc = track(spawn(getJavaCommand(), args, { windowsHide: true }));
+  const progress = createProgress({ text: 'Starting HL7 FHIR Validator server', verbose: showOutput, stream });
+  let starting = true;
+  const handler = createOutputHandler({
+    verbose: showOutput,
+    write: (text) => write(chalk.gray(text)),
+    maxChars: SERVER_OUTPUT_TAIL_CHARS,
+    onPhase: (label) => { if (starting) progress.phase(label); },
+    onChunk: (text) => { if (logStream) logStream.write(text); },
+  });
 
-  proc.stdout.on('data', d => process.stderr.write(chalk.gray(d.toString())));
-  proc.stderr.on('data', d => process.stderr.write(chalk.gray(d.toString())));
+  const proc = track(spawnFn(getJavaCommand(), args, { windowsHide: true }));
+  proc.stdout.on('data', handler.onData);
+  proc.stderr.on('data', handler.onData);
 
   let procExited = false;
   let procError = null;
+  let exitCode = null;
+  let exitSignal = null;
   proc.on('error', err => { procError = err; });
-  proc.on('exit', () => { procExited = true; });
+  proc.on('exit', (code, signal) => {
+    procExited = true;
+    exitCode = code;
+    exitSignal = signal || null;
+  });
+  proc.on('close', () => { if (logStream) logStream.end(); });
 
+  const isDead = () => procExited || !!procError;
   const stop = () => {
     if (!procExited) {
       try { proc.kill(); } catch { /* ignore */ }
@@ -163,22 +218,109 @@ async function startValidatorServer({ igIds, port = null, debug = false }) {
 
   try {
     // Brief pause to catch immediate startup failures (bad jar path, wrong Java, etc.)
-    await new Promise(r => setTimeout(r, 600));
+    await new Promise(r => setTimeout(r, startupGraceMs));
     if (procError) throw new Error(`Failed to start validator server: ${procError.message}`);
 
-    const deadline = Date.now() + READY_TIMEOUT_MS;
-    const isDead = () => procExited || !!procError;
+    const deadline = Date.now() + readyTimeoutMs;
 
-    await waitForPort(listenPort, deadline, isDead);
-    process.stderr.write(chalk.gray(`  Validator server accepting connections on port ${listenPort}, warming up...\n`));
+    await waitForPort(listenPort, deadline, isDead, pollIntervalMs);
+    if (showOutput) {
+      write(chalk.gray(`  Validator server accepting connections on port ${listenPort}, warming up...\n`));
+    } else {
+      progress.phase('Warming up');
+    }
 
     await warmupServer(listenPort, deadline, isDead);
   } catch (err) {
+    starting = false;
     stop();
-    throw err;
+    progress.fail('HL7 FHIR Validator server could not be started');
+    if (procError) throw err;
+    handler.flush();
+    throw createValidatorError({
+      subject: 'FHIR Java Validator server',
+      reason: `did not become ready (${err.message})`,
+      code: procExited ? exitCode : null,
+      signal: exitSignal,
+      rawOutput: handler.getOutput(),
+      logPath: logFile,
+    }, { cause: err });
+  }
+
+  starting = false;
+  progress.succeed(`HL7 FHIR Validator server ready on port ${listenPort}`);
+  if (logFile) write(chalk.gray(`  Server output: ${logFile}\n`));
+  return {
+    port: listenPort,
+    stop,
+    logFile,
+    isDead,
+    exitInfo: () => ({
+      exited: isDead(),
+      code: procExited ? exitCode : null,
+      signal: exitSignal,
+      error: procError ? procError.message : null,
+    }),
+    getOutput: () => { handler.flush(); return handler.getOutput(); },
+    tail: (n) => tailLines(handler.getOutput(), n),
+  };
+}
+
+/**
+ * Checks the results of a server batch for failed requests and, if there are
+ * any, explains them, so that a crashed or hung server is understandable
+ * without --verbose. A short grace period lets the JVM exit be noticed when the
+ * requests failed because it has just died.
+ *
+ * @param {object} server - Return value of startValidatorServer, or a reused
+ *                          server `{ port, stop }` without process information
+ * @param {Array<{error?: string}>} results - validateBatchViaServer results
+ * @param {object} [opts]
+ * @param {number} [opts.exitGraceMs] - How long to wait for a pending exit
+ * @returns {Promise<null|{ failed: number, total: number, dead: boolean, message: string, short: string }>}
+ *   null when every request got a result. `message` is the full explanation
+ *   (exit code, output tail, log path) for the console; `short` is one line for
+ *   per-profile errors, the JSON output and reports.
+ */
+async function describeBatchFailure(server, results, { exitGraceMs = 1000 } = {}) {
+  const total = results.length;
+  const failed = results.filter(r => r && r.error).length;
+  if (failed === 0) return null;
+
+  const canInspect = typeof server.isDead === 'function';
+  if (canInspect && !server.isDead() && exitGraceMs > 0) {
+    const until = Date.now() + exitGraceMs;
+    while (!server.isDead() && Date.now() < until) await new Promise(r => setTimeout(r, 50));
   }
+  const dead = canInspect && server.isDead();
+  const info = canInspect ? server.exitInfo() : { code: null, signal: null };
+  const logPath = server.logFile || null;
+
+  let reason;
+  if (dead) reason = 'did not finish the batch validation';
+  else if (failed === total) reason = `returned no result for any of the ${total} profile(s)`;
+  else reason = `returned no result for ${failed} of ${total} profile(s)`;
+
+  const message = canInspect
+    ? formatValidatorError({
+      subject: 'FHIR Java Validator server',
+      reason,
+      code: info.code,
+      signal: info.signal,
+      rawOutput: server.getOutput(),
+      logPath,
+    })
+    : `FHIR Java Validator server ${reason}.`;
+
+  const short = formatValidatorErrorShort({
+    subject: 'FHIR Java Validator server',
+    reason,
+    code: dead ? info.code : null,
+    signal: dead ? info.signal : null,
+    logPath,
+  });
 
-  return { port: listenPort, stop };
+  return { failed, total, dead, message, short };
 }
 
 /**
@@ -313,4 +455,5 @@ module.exports = {
   parseOperationOutcome,
   validateViaServer,
   validateBatchViaServer,
+  describeBatchFailure,
 };

package/src/lib/output.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Output streams of the CLI.
+ *
+ * - Progress (status lines, lists, spinners from ora) always goes to stderr, so
+ *   all human progress output shares one stream and keeps its order when stdout
+ *   and stderr are captured separately (e.g. Docker logs, CI) or merged.
+ * - The final result (e.g. the PASS/FAIL summary and the report path) goes to
+ *   stdout, unless --json is set: then stdout carries only the JSON document and
+ *   the human result goes to stderr as well.
+ */
+
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/**
+ * chalk decides about colors based on stdout. When stdout is a terminal but
+ * stderr is redirected, strip the color codes from stderr lines so log files
+ * stay readable. FORCE_COLOR keeps the colors.
+ */
+function stripColorsForStream(stream, text) {
+  if (stream.isTTY || process.env.FORCE_COLOR) return text;
+  return text.replace(ANSI_RE, '');
+}
+
+/** Returns a console.log-like writer for the given stream (args joined with a space). */
+function writerFor(stream) {
+  return (...args) => {
+    stream.write(stripColorsForStream(stream, args.join(' ')) + '\n');
+  };
+}
+
+/** Progress logger: always stderr (same stream as the ora spinners). */
+function makeProgressLogger() {
+  return writerFor(process.stderr);
+}
+
+/** Result logger: stdout, or stderr with --json (stdout is reserved for the JSON document). */
+function makeResultLogger(options = {}) {
+  return options.json ? writerFor(process.stderr) : writerFor(process.stdout);
+}
+
+module.exports = { makeProgressLogger, makeResultLogger, stripColorsForStream };

package/src/lib/preflight.js

@@ -13,7 +13,7 @@ const { ensureJava, requiredJavaMajor } = require('./javaCheck');
 const { resolvePackageDir, packageHasSnapshots, downloadFhirPackage } = require('./fhirPkgTool');
 const { CliError } = require('./errors');
 
-const stderrLog = (...args) => process.stderr.write(args.join(' ') + '\n');
+const stderrLog = require('./output').makeProgressLogger();
 
 /**
  * Lists what `init` should have installed but is missing (pure-ish; no Java needed).