packages/mosaic/src/stages/gateway-config.spec.ts

@@ -136,6 +136,7 @@ describe('gatewayConfigStage', () => {
     delete process.env['MOSAIC_STORAGE_TIER'];
     delete process.env['MOSAIC_DATABASE_URL'];
     delete process.env['MOSAIC_VALKEY_URL'];
+    delete process.env['MOSAIC_GATEWAY_SKIP_NPM_INSTALL'];
   });
 
   afterEach(() => {
@@ -167,6 +168,36 @@ describe('gatewayConfigStage', () => {
     expect(state.gateway?.regeneratedConfig).toBe(true);
   });
 
+  it('installs the gateway package on fresh install when skipInstall is not set', async () => {
+    const p = buildPrompter();
+    const state = makeState('/home/user/.config/mosaic');
+
+    const result = await gatewayConfigStage(p, state, {
+      host: 'localhost',
+      defaultPort: 14242,
+      skipInstall: false,
+    });
+
+    expect(result.ready).toBe(true);
+    expect(daemonState.installPkgCalled).toBe(1);
+  });
+
+  it('honors MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1 and skips the registry install (dev/offline installs)', async () => {
+    process.env['MOSAIC_GATEWAY_SKIP_NPM_INSTALL'] = '1';
+    const p = buildPrompter();
+    const state = makeState('/home/user/.config/mosaic');
+
+    const result = await gatewayConfigStage(p, state, {
+      host: 'localhost',
+      defaultPort: 14242,
+      skipInstall: false,
+    });
+
+    // The source-built global gateway must NOT be overwritten by @latest.
+    expect(result.ready).toBe(true);
+    expect(daemonState.installPkgCalled).toBe(0);
+  });
+
   it('does not ask for a gateway API key when provider setup was completed with no key', async () => {
     delete process.env['MOSAIC_ASSUME_YES'];
     const originalIsTTY = process.stdin.isTTY;

packages/mosaic/src/stages/gateway-config.ts

@@ -294,7 +294,12 @@ export async function gatewayConfigStage(
   }
 
   // Install the gateway npm package on first install or after failure.
-  if (!opts.skipInstall && !daemonRunning) {
+  // MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1 forces a skip even without opts.skipInstall:
+  // used by dev/offline installs where @mosaicstack/gateway is already present
+  // globally (e.g. a build-from-source `install.sh --dev`) and must not be
+  // overwritten by the registry @latest build.
+  const skipNpmInstall = opts.skipInstall || process.env['MOSAIC_GATEWAY_SKIP_NPM_INSTALL'] === '1';
+  if (!skipNpmInstall && !daemonRunning) {
     installGatewayPackage();
   }