Merge hotfix/propagate-child-events-to-parent into main (#228)

Hotfix release v1.0.2

fix(cli): prevent missing child exit events in parent process

Author: patoale

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [1.0.2](https://github.com/patoale/envloadr/compare/v1.0.1...v1.0.2) (August 7, 2025)
+
+- Fixed main process exiting with code 0 regardless of child’s exit code. (@patoale in #228)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "envloadr",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Simplifies the process of loading environment variables from files",
   "bin": {
     "envloadr": "bin/cli.js"

src/cli/index.ts

@@ -5,10 +5,11 @@ import {
   DEFAULT_VERBOSE,
 } from '@/config';
 import { parseEnvFiles } from '@/envFile';
+import { buildHelp } from './help';
 import { parse } from './parser';
 import schema from './schema';
-import { buildHelp } from './help';
-import type { Options } from './parser/types';
+import { syncEvents } from './utils/childProcess';
+import type { Command, Options } from './parser/types';
 
 function normalizeOptions(options: Options<typeof schema> | undefined) {
   const files = options?.files ?? [DEFAULT_ENV_FILE_PATH];
@@ -19,6 +20,15 @@ function normalizeOptions(options: Options<typeof schema> | undefined) {
   return { files, override, verbose };
 }
 
+function executeCommand({ args, name }: Command, env: NodeJS.ProcessEnv) {
+  const child = spawn(name, args, {
+    stdio: 'inherit',
+    env,
+  });
+
+  syncEvents(process, child);
+}
+
 export function run() {
   const args = process.argv.slice(2);
 
@@ -29,10 +39,10 @@ export function run() {
   }
 
   const { files, override, verbose } = normalizeOptions(options);
-  const env = parseEnvFiles(files, { override, verbose });
+  const customEnv = parseEnvFiles(files, { override, verbose });
 
-  spawn(command.name, command.args, {
-    stdio: 'inherit',
-    env: override ? { ...process.env, ...env } : { ...env, ...process.env },
-  });
+  const env = override
+    ? { ...process.env, ...customEnv }
+    : { ...customEnv, ...process.env };
+  executeCommand(command, env);
 }

src/cli/parser/types.ts

@@ -28,14 +28,16 @@ type OptionType<T extends OptionSpecParam | undefined> = T extends BooleanType
     ? OptionSpecTypeMap[T['type']]
     : boolean;
 
+export type Command = {
+  name: string;
+  args: string[];
+};
+
 export type Options<T extends SpecSchema> = {
   [K in keyof T]?: OptionType<T[K]['param']>;
 };
 
 export type Args<T extends SpecSchema> = {
-  command: {
-    name: string;
-    args: string[];
-  };
+  command: Command;
   options?: Options<T>;
 };

src/cli/utils/childProcess.ts

@@ -0,0 +1,52 @@
+import { ChildProcess } from 'child_process';
+
+const SIGNALS: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+type SignalListener = {
+  signal: NodeJS.Signals;
+  listener: () => boolean;
+};
+
+function propagateExit(
+  sourceProcess: ChildProcess,
+  targetProcess: NodeJS.Process,
+  cleanupListeners: SignalListener[],
+) {
+  sourceProcess.on('exit', (code, signal) => {
+    cleanupListeners.forEach(({ signal, listener }) =>
+      targetProcess.removeListener(signal, listener),
+    );
+
+    if (signal !== null) targetProcess.kill(targetProcess.pid, signal);
+    else targetProcess.exit(code ?? 1);
+  });
+
+  sourceProcess.on('error', (err) => {
+    console.error(
+      `Command "${sourceProcess.spawnargs.join(' ')}" failed to launch: ${err.message}`,
+    );
+
+    targetProcess.exit(1);
+  });
+}
+
+function propagateSignals(
+  sourceProcess: NodeJS.Process,
+  targetProcess: ChildProcess,
+) {
+  const listeners = SIGNALS.map((signal) => ({
+    signal,
+    listener: () => targetProcess.kill(signal),
+  }));
+
+  listeners.forEach(({ listener, signal }) =>
+    sourceProcess.on(signal, listener),
+  );
+
+  return listeners;
+}
+
+export function syncEvents(parent: NodeJS.Process, child: ChildProcess): void {
+  const removeListeners = propagateSignals(parent, child);
+  propagateExit(child, parent, removeListeners);
+}

test/cli/index.spec.ts

@@ -8,6 +8,7 @@ import { run } from '@/cli';
 import { buildHelp } from '@/cli/help';
 import * as cliParser from '@/cli/parser';
 import schema from '@/cli/schema';
+import * as childProcessUtils from '@/cli/utils/childProcess';
 import * as envFile from '@/envFile';
 import type { Args, SpecSchema } from '@/cli/parser/types';
 
@@ -18,6 +19,7 @@ describe('run', () => {
   >;
   let parseEnvFilesSpy: jest.SpyInstance;
   let spawnSpy: jest.SpyInstance;
+  let syncEventsSpy: jest.SpyInstance;
 
   beforeAll(() => {
     // Testing these functions is not the objective of this suite,
@@ -27,12 +29,16 @@ describe('run', () => {
       .spyOn(envFile, 'parseEnvFiles')
       .mockImplementation();
     spawnSpy = jest.spyOn(childProcess, 'spawn').mockImplementation();
+    syncEventsSpy = jest
+      .spyOn(childProcessUtils, 'syncEvents')
+      .mockImplementation();
   });
 
   afterAll(() => {
     cliParseSpy.mockRestore();
     parseEnvFilesSpy.mockRestore();
     spawnSpy.mockRestore();
+    syncEventsSpy.mockRestore();
   });
 
   it('should print help message when help option is enabled', () => {

test/cli/utils/childProcess.spec.ts

@@ -0,0 +1,102 @@
+import { syncEvents } from '@/cli/utils/childProcess';
+
+import { ChildProcess } from 'child_process';
+import { EventEmitter } from 'events';
+
+describe('syncEvents', () => {
+  const mockChildKill = jest.fn();
+  const mockParentExit = jest.fn();
+  const mockParentKill = jest.fn();
+  const mockParentRemoveListener = jest.fn();
+
+  let child: ChildProcess;
+  let parent: NodeJS.Process;
+
+  beforeEach(() => {
+    parent = Object.assign(new EventEmitter(), {
+      exit: mockParentExit,
+      kill: mockParentKill,
+      removeListener: mockParentRemoveListener,
+    }) as unknown as NodeJS.Process;
+
+    child = Object.assign(new EventEmitter(), {
+      kill: mockChildKill,
+      spawnargs: ['node', 'example.js'],
+    }) as unknown as ChildProcess;
+  });
+
+  it("should exit parent process with child's exit code when child exits normally", () => {
+    syncEvents(parent, child);
+
+    child.emit('exit', 0, null);
+
+    expect(mockParentExit).toHaveBeenCalledWith(0);
+  });
+
+  it('should exit parent process with code 1 when child exits with null code', () => {
+    syncEvents(parent, child);
+
+    child.emit('exit', null, null);
+
+    expect(mockParentExit).toHaveBeenCalledWith(1);
+  });
+
+  it('should terminate parent process with same signal when child is killed by signal', () => {
+    syncEvents(parent, child);
+
+    child.emit('exit', null, 'SIGTERM');
+
+    expect(mockParentKill).toHaveBeenCalledWith(parent.pid, 'SIGTERM');
+  });
+
+  it('should log error when child fails to launch', () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+
+    try {
+      syncEvents(parent, child);
+
+      child.emit('error', new Error('Launch failed'));
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Command "node example.js" failed to launch: Launch failed',
+      );
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it('should exit parent process with code 1 when child fails to launch', () => {
+    syncEvents(parent, child);
+
+    child.emit('error', new Error('Launch failed'));
+
+    expect(mockParentExit).toHaveBeenCalledWith(1);
+  });
+
+  it('should terminate child process with same signal when parent is killed by signal', () => {
+    syncEvents(parent, child);
+
+    parent.emit('SIGTERM');
+
+    expect(mockChildKill).toHaveBeenCalledWith('SIGTERM');
+  });
+
+  it("should remove child's signal listeners from parent process when child exits", () => {
+    syncEvents(parent, child);
+
+    child.emit('exit', 0, null);
+
+    expect(mockParentRemoveListener).toHaveBeenCalledWith(
+      'SIGINT',
+      expect.any(Function),
+    );
+    expect(mockParentRemoveListener).toHaveBeenCalledWith(
+      'SIGTERM',
+      expect.any(Function),
+    );
+    expect(mockParentRemoveListener).toHaveBeenCalledWith(
+      'SIGHUP',
+      expect.any(Function),
+    );
+  });
+});