fix(api): keep plugin config loads side-effect free (#2025)

## Summary

Makes API config loading side-effect free for CLI plugin management
commands, so plugin install operations preserve the plugin list they are
updating.

## Root Cause

`loadApiConfig()` always ran the stale Connect cleanup when
`/boot/config/plugins/dynamix.unraid.net.plg` was not visible. CLI
plugin commands also load API config, so an install command could remove
`unraid-api-plugin-connect` while trying to add it.

During Unraid plugin-manager installation, the Connect `.plg` may not be
committed to `/boot/config/plugins` yet. That allowed the API package to
install and restart successfully while `api.json` still contained
`"plugins": []`, so the Connect Nest module never loaded.

## Change

- Gates the stale Connect cleanup on `environment.IS_MAIN_PROCESS`.
- Keeps CLI config loading side-effect free for plugin management
operations.
- Preserves the existing runtime cleanup behavior when the main API
process starts.
- Adds tests for both CLI-style config loading and main-process cleanup.
- Builds `@unraid/shared` before API type-check so workspace
package-exported types are current in CI.

## Validation

- `pnpm -C api run type-check`
- `pnpm -C api exec vitest run src/unraid-api/config/api-config.test.ts`
- `pnpm --filter @unraid/connect-plugin test`
- Prior to broadening this fix, installed a patched `.plg` on
`root@unraid.local` and verified the expected runtime outcome:
- install output included `Added bundled plugin
unraid-api-plugin-connect`
  - `api.json` contained `"plugins": ["unraid-api-plugin-connect"]`
- `unraid-api plugins list` reported
`unraid-api-plugin-connect@file:packages/unraid-api-plugin-connect-4.25.3.tgz`
- `/var/log/graphql-api.log` showed `ConnectPluginModule` initialized
and Mothership connected

Note: an accidental full `pnpm --filter ./api test --
api/src/unraid-api/config/api-config.test.ts` run executed the broader
API suite and surfaced an existing unrelated metrics spec failure in
`metrics.resolver.spec.ts`; the focused config test passes.

Author: elibosley

api/package.json

@@ -35,6 +35,7 @@
         "// Code Quality": "",
         "lint": "eslint --config .eslintrc.ts src/",
         "lint:fix": "eslint --fix --config .eslintrc.ts src/",
+        "pretype-check": "pnpm --filter @unraid/shared build",
         "type-check": "tsc --noEmit",
         "// Testing": "",
         "test": "NODE_ENV=test vitest run",

api/src/unraid-api/config/api-config.module.ts

@@ -7,7 +7,7 @@ import { ConfigFilePersister } from '@unraid/shared/services/config-file.js';
 import { csvStringToArray } from '@unraid/shared/util/data.js';
 
 import { isConnectPluginInstalled } from '@app/connect-plugin-cleanup.js';
-import { API_VERSION, PATHS_CONFIG_MODULES } from '@app/environment.js';
+import { API_VERSION, environment, PATHS_CONFIG_MODULES } from '@app/environment.js';
 import { OnboardingTrackerModule } from '@app/unraid-api/config/onboarding-tracker.module.js';
 
 export { type ApiConfig };
@@ -31,8 +31,9 @@ export const loadApiConfig = async () => {
     const apiHandler = new ApiConfigPersistence(new ConfigService()).getFileHandler();
 
     const diskConfig: Partial<ApiConfig> = await apiHandler.loadConfig();
-    // Hack: cleanup stale connect plugin entry if necessary
-    if (!isConnectPluginInstalled()) {
+    // Hack: cleanup stale connect plugin entry if necessary.
+    // Keep config loading side-effect free for CLI plugin management commands.
+    if (environment.IS_MAIN_PROCESS && !isConnectPluginInstalled()) {
         diskConfig.plugins = diskConfig.plugins?.filter(
             (plugin) => plugin !== 'unraid-api-plugin-connect'
         );

api/src/unraid-api/config/api-config.test.ts

@@ -3,15 +3,22 @@ import { readFile } from 'fs/promises';
 import path from 'path';
 
 import type { ApiConfig } from '@unraid/shared/services/api-config.js';
-import { writeFile as atomicWriteFile } from 'atomically';
+import { fileExists as sharedFileExists } from '@unraid/shared/util/file.js';
+import { readFile as atomicReadFile, writeFile as atomicWriteFile } from 'atomically';
 import { Subject } from 'rxjs';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { API_VERSION, PATHS_CONFIG_MODULES } from '@app/environment.js';
+import { API_VERSION, environment, PATHS_CONFIG_MODULES } from '@app/environment.js';
 import { ApiConfigPersistence, loadApiConfig } from '@app/unraid-api/config/api-config.module.js';
 import { OnboardingOverrideService } from '@app/unraid-api/config/onboarding-override.service.js';
 import { OnboardingTrackerService } from '@app/unraid-api/config/onboarding-tracker.module.js';
 
+const connectPluginCleanupMocks = vi.hoisted(() => ({
+    isConnectPluginInstalled: vi.fn(),
+}));
+
+vi.mock('@app/connect-plugin-cleanup.js', () => connectPluginCleanupMocks);
+
 vi.mock('@app/core/utils/files/file-exists.js', () => ({
     fileExists: vi.fn(),
 }));
@@ -39,10 +46,13 @@ vi.mock('@app/store/index.js', () => ({
 }));
 
 vi.mock('atomically', () => ({
+    readFile: vi.fn(),
     writeFile: vi.fn(),
 }));
 
 const mockReadFile = vi.mocked(readFile);
+const mockSharedFileExists = vi.mocked(sharedFileExists);
+const mockAtomicReadFile = vi.mocked(atomicReadFile);
 const mockAtomicWriteFile = vi.mocked(atomicWriteFile);
 
 const createOnboardingTracker = (configService: ConfigService) => {
@@ -296,6 +306,10 @@ describe('OnboardingTracker', () => {
 describe('loadApiConfig', () => {
     beforeEach(() => {
         vi.clearAllMocks();
+        environment.IS_MAIN_PROCESS = false;
+        mockSharedFileExists.mockResolvedValue(false);
+        mockAtomicReadFile.mockRejectedValue(new Error('Not found'));
+        connectPluginCleanupMocks.isConnectPluginInstalled.mockReturnValue(false);
     });
 
     it('should return default config with current API_VERSION', async () => {
@@ -321,4 +335,62 @@ describe('loadApiConfig', () => {
             plugins: [],
         });
     });
+
+    it('does not clean stale Connect plugin entries outside the main API process', async () => {
+        mockSharedFileExists.mockResolvedValue(true);
+        mockAtomicReadFile.mockResolvedValue(
+            Buffer.from(
+                JSON.stringify({
+                    version: API_VERSION,
+                    extraOrigins: [],
+                    sandbox: true,
+                    ssoSubIds: [],
+                    plugins: ['unraid-api-plugin-connect'],
+                })
+            )
+        );
+
+        const result = await loadApiConfig();
+
+        expect(connectPluginCleanupMocks.isConnectPluginInstalled).not.toHaveBeenCalled();
+        expect(mockAtomicWriteFile).not.toHaveBeenCalled();
+        expect(result).toEqual({
+            version: API_VERSION,
+            extraOrigins: [],
+            sandbox: true,
+            ssoSubIds: [],
+            plugins: ['unraid-api-plugin-connect'],
+        });
+    });
+
+    it('cleans stale Connect plugin entries in the main API process', async () => {
+        environment.IS_MAIN_PROCESS = true;
+        mockSharedFileExists.mockResolvedValue(true);
+        mockAtomicReadFile.mockResolvedValue(
+            Buffer.from(
+                JSON.stringify({
+                    version: API_VERSION,
+                    extraOrigins: [],
+                    sandbox: true,
+                    ssoSubIds: [],
+                    plugins: ['unraid-api-plugin-connect', 'other-plugin'],
+                })
+            )
+        );
+
+        const result = await loadApiConfig();
+
+        expect(connectPluginCleanupMocks.isConnectPluginInstalled).toHaveBeenCalledOnce();
+        expect(mockAtomicWriteFile).toHaveBeenCalledWith(
+            path.join(PATHS_CONFIG_MODULES, 'api.json'),
+            expect.not.stringContaining('unraid-api-plugin-connect')
+        );
+        expect(result).toEqual({
+            version: API_VERSION,
+            extraOrigins: [],
+            sandbox: true,
+            ssoSubIds: [],
+            plugins: ['other-plugin'],
+        });
+    });
 });