feat(desktop-main): fix-path on boot to inherit login-shell PATH (#225)

Closes #148

## Summary

- Adds `fix-path ^4.0.0` as a runtime dependency of
`@hyveon/desktop-main`
- Creates `fix-path-bootstrap.ts` — a thin wrapper that calls `fix-path`
on macOS/Linux and is a no-op on Windows; `process.platform` is read at
call-time so tests can stub it cleanly
- Calls `applyFixPath()` as the very first executable statement in
`main.ts`, before the Electron-version guard and `bootstrap()`, ensuring
PATH is fixed before any `child_process.spawn` for terraform/aws
- Adds 3 unit tests in `fix-path-bootstrap.test.ts` (darwin calls
fix-path, linux calls fix-path, win32 skips) and extends `main.test.ts`
with a spy asserting `applyFixPath` is invoked during bootstrap (500
tests passing)

## Implementation notes

- `fix-path` v4 is pure ESM, compatible with `desktop-main`'s `"type":
"module"` and the ESNext module target in `tsconfig.base.json`
- The indirection through `fix-path-bootstrap.ts` is required so
`main.test.ts` can intercept the module boundary with `vi.mock` — a
top-level ESM side-effect in `main.ts` itself would race the test setup
- The issue acceptance criterion "integration test asserts
`process.env.PATH` includes `/opt/homebrew/bin` on a fixture machine" is
deferred to a future issue — the Electron e2e tier (Epic F, #135) does
not exist yet. The unit tests here prove the wiring is correct; a real
fixture test can be added once the Playwright Electron tier lands.

## Test plan

- [ ] `npm run app:test` — 500 tests pass
- [ ] `npm run app:lint` — 0 errors
- [ ] On macOS with Homebrew: packaged app can find `terraform` on PATH
(manual smoke test)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: CoderCoco

app/packages/desktop-main/package.json

@@ -23,6 +23,7 @@
     "@nestjs/microservices": "^10.4.0",
     "@nestjs/platform-express": "^10.4.0",
     "express": "^4.19.2",
+    "fix-path": "^4.0.0",
     "nestjs-electron-ipc-transport": "^1.0.2",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",

app/packages/desktop-main/src/fix-path-bootstrap.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+/*
+ * Hoist the mock spy so it is available when vi.mock() factory runs (vi.mock
+ * calls are hoisted above regular declarations in compiled output).
+ */
+const { fixPathMock } = vi.hoisted(() => {
+  /** Spy standing in for fix-path's default export (the shell-spawning function). */
+  const fixPathMock = vi.fn();
+  return { fixPathMock };
+});
+
+/**
+ * Mock the fix-path ESM module so no real login shell is ever spawned during
+ * tests. Its default export is replaced with a vi.fn() we can assert on.
+ */
+vi.mock('fix-path', () => ({
+  default: fixPathMock,
+}));
+
+// Import the module under test AFTER mocks are registered.
+import { applyFixPath } from './fix-path-bootstrap.js';
+
+describe('applyFixPath', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it('should call fix-path when platform is darwin', () => {
+    vi.stubGlobal('process', { ...process, platform: 'darwin' });
+
+    applyFixPath();
+
+    expect(vi.mocked(fixPathMock)).toHaveBeenCalledOnce();
+  });
+
+  it('should call fix-path when platform is linux', () => {
+    vi.stubGlobal('process', { ...process, platform: 'linux' });
+
+    applyFixPath();
+
+    expect(vi.mocked(fixPathMock)).toHaveBeenCalledOnce();
+  });
+
+  it('should NOT call fix-path when platform is win32', () => {
+    vi.stubGlobal('process', { ...process, platform: 'win32' });
+
+    applyFixPath();
+
+    expect(vi.mocked(fixPathMock)).not.toHaveBeenCalled();
+  });
+});

app/packages/desktop-main/src/fix-path-bootstrap.ts

@@ -0,0 +1,22 @@
+import fixPath from 'fix-path';
+
+/**
+ * Applies the fix-path workaround for GUI applications on macOS and Linux.
+ *
+ * When an application is launched from a graphical environment (e.g. a dock,
+ * file manager, or Electron shell) rather than a terminal, the process does not
+ * inherit the user's login shell PATH. This means executables that are only
+ * available after sourcing `~/.profile`, `~/.bashrc`, `~/.zshrc`, etc. — such
+ * as `node`, `aws`, or any tool installed via nvm/homebrew — will not be found.
+ *
+ * fix-path resolves this by spawning a login shell, reading its PATH, and
+ * applying it to the current process before any child processes are started.
+ *
+ * This function is a no-op on Windows, where the problem does not apply.
+ */
+export function applyFixPath(): void {
+  if (process.platform === 'win32') {
+    return;
+  }
+  fixPath();
+}

app/packages/desktop-main/src/main.test.ts

@@ -6,14 +6,16 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
  * vi.mock() factory functions run (vi.mock calls are hoisted to the top of the
  * compiled output, above regular const/let declarations).
  */
-const { ElectronIPCTransportMock, fakeApp, createMicroserviceMock } = vi.hoisted(() => {
+const { ElectronIPCTransportMock, fakeApp, createMicroserviceMock, applyFixPathMock } = vi.hoisted(() => {
   /** Fake NestJS microservice app returned by `NestFactory.createMicroservice`. */
   const fakeApp = { listen: vi.fn().mockResolvedValue(undefined) };
   /** Spy constructor for ElectronIPCTransport — tracks `new` invocations. */
   const ElectronIPCTransportMock = vi.fn().mockImplementation(() => ({}));
   /** Spy for `NestFactory.createMicroservice`. */
   const createMicroserviceMock = vi.fn().mockResolvedValue(fakeApp);
-  return { ElectronIPCTransportMock, fakeApp, createMicroserviceMock };
+  /** Spy for `applyFixPath` — verifies the fix-path bootstrap is called during startup. */
+  const applyFixPathMock = vi.fn();
+  return { ElectronIPCTransportMock, fakeApp, createMicroserviceMock, applyFixPathMock };
 });
 
 vi.mock('nestjs-electron-ipc-transport', () => ({
@@ -35,6 +37,10 @@ vi.mock('./app.module.js', () => ({
   AppModule: class AppModule {},
 }));
 
+vi.mock('./fix-path-bootstrap.js', () => ({
+  applyFixPath: applyFixPathMock,
+}));
+
 describe('main bootstrap', () => {
   beforeEach(() => {
     /*
@@ -45,6 +51,7 @@ describe('main bootstrap', () => {
     ElectronIPCTransportMock.mockImplementation(() => ({}));
     createMicroserviceMock.mockResolvedValue(fakeApp);
     fakeApp.listen.mockResolvedValue(undefined);
+    applyFixPathMock.mockImplementation(() => undefined);
     // Simulate an Electron main-process environment so the module-level guard passes.
     vi.stubGlobal('process', { ...process, versions: { ...process.versions, electron: '36.0.0' } });
   });
@@ -92,4 +99,15 @@ describe('main bootstrap', () => {
     // listen() should have been called on the fake app.
     expect(fakeApp.listen).toHaveBeenCalledOnce();
   });
+
+  it('should call applyFixPath during bootstrap', async () => {
+    vi.resetModules();
+    await import('./main.js');
+
+    // Flush the event loop so the async bootstrap chain fully resolves.
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    // applyFixPath must be invoked exactly once before NestFactory.createMicroservice.
+    expect(applyFixPathMock).toHaveBeenCalledTimes(1);
+  });
 });

app/packages/desktop-main/src/main.ts

@@ -3,6 +3,9 @@ import { NestFactory } from '@nestjs/core';
 import { MicroserviceOptions } from '@nestjs/microservices';
 import { ElectronIPCTransport } from 'nestjs-electron-ipc-transport';
 import { AppModule } from './app.module.js';
+import { applyFixPath } from './fix-path-bootstrap.js';
+
+applyFixPath();
 
 // ElectronIPCTransport requires ipcMain, which is only available inside an
 // Electron main process. Fail fast with a readable message rather than a