fix(cli): prevent dependency install from hanging on link/deploy setup (#3107)

* fix(cli): prevent dependency install from hanging on link/deploy setup

The install step in `catalyst project link` and the `catalyst deploy`
first-run setup could hang forever on "Installing dependencies...". nypm
was called with `silent: true`, which pipes the child's stdio; since nypm
routes pnpm/yarn through corepack, corepack's package-manager download
confirmation prompt blocked on stdin that never arrived — an invisible,
unanswerable deadlock.

Inherit stdio instead so corepack/pnpm prompts and progress are visible
and answerable. Also detect the project's actual package manager from its
lockfile in the link/deploy setup paths instead of always defaulting to
pnpm, so npm/yarn/bun projects aren't forced through corepack pnpm.

Refs LTRAC-1224
Co-Authored-By: Claude <noreply@anthropic.com>

* fix(cli): silence child stderr flood that deadlocked dependency install

The real cause of the install hang was not corepack's prompt: nypm runs the
install via tinyexec, which in silent mode fully drains the child's stdout
before it reads stderr. pnpm sends progress to stdout but floods stderr with
Node warnings (on Node 26, thousands of "File descriptor N opened in unmanaged
mode" lines). That stderr fills its ~64KB pipe buffer while tinyexec is still
on stdout, pnpm blocks writing, and the install deadlocks. Inheriting stdio
avoided the deadlock but surfaced the warning spam in the terminal.

Keep the silent spinner UX and instead starve the flood: run the install child
with NODE_NO_WARNINGS=1 (drops the internal Node warnings) and pin
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 defensively. Both are saved and restored so
they don't leak into later CLI operations.

Refs LTRAC-1224
Co-Authored-By: Claude <noreply@anthropic.com>

* fix(cli): default project package manager fallback to npm

Detection of an existing project's package manager fell back to pnpm
when a lockfile or packageManager field couldn't be resolved. Most
users have npm installed by default, so default there instead — pnpm
requires an extra install step most contributors won't have.

Refs LTRAC-1224
Co-Authored-By: Claude <noreply@anthropic.com>

---------

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

Author: jorgemoya

.changeset/install-dependencies-corepack-hang.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst": patch
+---
+
+Fix the dependency install step hanging indefinitely during `catalyst project link` and the `catalyst deploy` first-run setup. nypm runs the install through tinyexec, which in silent mode drains the child's stdout to completion before it reads stderr; pnpm floods stderr with Node warnings (on Node 26, thousands of `File descriptor N opened in unmanaged mode` lines), filling the stderr pipe buffer while tinyexec is still on stdout, so pnpm blocks writing and the install deadlocks. The install now runs the child with `NODE_NO_WARNINGS` (and pins `COREPACK_ENABLE_DOWNLOAD_PROMPT` off) so stderr never fills. The `link`/`deploy` setup paths also now detect the project's actual package manager from its lockfile instead of always forcing pnpm.

packages/catalyst/src/cli/commands/deploy.spec.ts

@@ -828,7 +828,7 @@ describe('transformation guard', () => {
       storeHash,
       accessToken,
     });
-    expect(installDependencies).toHaveBeenCalledWith(tmpDir);
+    expect(installDependencies).toHaveBeenCalledWith(tmpDir, expect.any(String));
   });
 
   test('exits gracefully when user declines to run setup', async () => {

packages/catalyst/src/cli/commands/deploy.ts

@@ -17,6 +17,7 @@ import {
   setupCommerceHosting,
 } from '../lib/commerce-hosting';
 import { getDeploymentErrorMessage } from '../lib/deployment-errors';
+import { detectProjectPackageManager } from '../lib/detect-package-manager';
 import {
   getStoredEnv,
   mergeDeploymentSecrets,
@@ -493,7 +494,11 @@ Example:
       await setupCommerceHosting({ projectDir, projectUuid, storeHash, accessToken });
       consola.success('Commerce Hosting setup complete.');
 
-      await installDependencies(projectDir);
+      // Match the manager the project was scaffolded with (from its lockfile),
+      // rather than forcing pnpm on npm/yarn/bun projects.
+      const packageManager = await detectProjectPackageManager(projectDir);
+
+      await installDependencies(projectDir, packageManager);
     } else {
       // Existing Commerce Hosting users may carry artifacts incompatible with
       // the Cloudflare worker bundle from earlier Catalyst versions

packages/catalyst/src/cli/commands/project.ts

@@ -8,6 +8,7 @@ import {
   selectOrCreateInfrastructureProject,
   setupCommerceHosting,
 } from '../lib/commerce-hosting';
+import { detectProjectPackageManager } from '../lib/detect-package-manager';
 import { installDependencies } from '../lib/install-dependencies';
 import { consola } from '../lib/logger';
 import { LoginAbortedError, login as runInteractiveLogin } from '../lib/login';
@@ -59,7 +60,11 @@ async function offerCommerceHostingSetup(
 
   consola.success('Commerce Hosting setup complete.');
 
-  await installDependencies(projectDir);
+  // Match the manager the project was scaffolded with (from its lockfile),
+  // rather than forcing pnpm on npm/yarn/bun projects.
+  const packageManager = await detectProjectPackageManager(projectDir);
+
+  await installDependencies(projectDir, packageManager);
 }
 
 const list = new Command('list')

packages/catalyst/src/cli/lib/detect-package-manager.spec.ts

@@ -0,0 +1,68 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { detectPackageManager as detectFromDir } from 'nypm';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { detectProjectPackageManager } from './detect-package-manager';
+
+// nypm's own fallback sniffs process.argv[1] for a package manager's name, which
+// spuriously matches 'pnpm' in this pnpm-managed monorepo (test runner path
+// contains `.pnpm`). Spy on it so the "nothing detectable" case below tests our
+// fallback instead of that environment artifact.
+vi.mock('nypm', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('nypm')>();
+
+  return { ...actual, detectPackageManager: vi.fn(actual.detectPackageManager) };
+});
+
+let projectDir: string;
+
+beforeEach(() => {
+  projectDir = mkdtempSync(join(tmpdir(), 'catalyst-detect-pm-'));
+});
+
+afterEach(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('detectProjectPackageManager', () => {
+  it('detects pnpm from a pnpm-lock.yaml', async () => {
+    writeFileSync(join(projectDir, 'pnpm-lock.yaml'), '');
+
+    await expect(detectProjectPackageManager(projectDir)).resolves.toBe('pnpm');
+  });
+
+  it('detects npm from a package-lock.json', async () => {
+    writeFileSync(join(projectDir, 'package-lock.json'), '{}');
+
+    await expect(detectProjectPackageManager(projectDir)).resolves.toBe('npm');
+  });
+
+  it('detects yarn from a yarn.lock', async () => {
+    writeFileSync(join(projectDir, 'yarn.lock'), '');
+
+    await expect(detectProjectPackageManager(projectDir)).resolves.toBe('yarn');
+  });
+
+  it('detects bun from a bun.lock', async () => {
+    writeFileSync(join(projectDir, 'bun.lock'), '');
+
+    await expect(detectProjectPackageManager(projectDir)).resolves.toBe('bun');
+  });
+
+  it('honors the package.json packageManager field', async () => {
+    writeFileSync(
+      join(projectDir, 'package.json'),
+      JSON.stringify({ packageManager: 'yarn@4.0.0' }),
+    );
+
+    await expect(detectProjectPackageManager(projectDir)).resolves.toBe('yarn');
+  });
+
+  it('falls back to npm when nothing is detectable', async () => {
+    vi.mocked(detectFromDir).mockResolvedValueOnce(undefined);
+
+    await expect(detectProjectPackageManager(projectDir)).resolves.toBe('npm');
+  });
+});

packages/catalyst/src/cli/lib/detect-package-manager.ts

@@ -1,3 +1,5 @@
+import { detectPackageManager as detectFromDir } from 'nypm';
+
 export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
 
 // Detect the package manager that INVOKED the CLI (via npx / pnpm dlx / yarn dlx
@@ -20,3 +22,21 @@ export const detectPackageManager = (): PackageManager => {
 
   return 'npm';
 };
+
+// Detect the package manager an EXISTING project uses, from its lockfile or the
+// package.json `packageManager` field. Used by flows that run inside an
+// already-scaffolded project (e.g. `project link`), where a lockfile exists —
+// unlike detectPackageManager(), which infers the INVOKING manager for a freshly
+// extracted project that has no lockfile yet. Falls back to npm, since most
+// users will have it installed, when detection is inconclusive or returns a
+// manager we don't support.
+export const detectProjectPackageManager = async (projectDir: string): Promise<PackageManager> => {
+  const detected = await detectFromDir(projectDir);
+  const name = detected?.name;
+
+  if (name === 'pnpm' || name === 'yarn' || name === 'bun' || name === 'npm') {
+    return name;
+  }
+
+  return 'npm';
+};

packages/catalyst/src/cli/lib/install-dependencies.ts

@@ -3,6 +3,43 @@ import yoctoSpinner from 'yocto-spinner';
 
 import type { PackageManager } from './detect-package-manager';
 
+// Restore an env var to a captured previous value, unsetting it when it wasn't
+// set before (a plain assignment can't represent "absent").
+const restoreEnv = (key: string, previous: string | undefined) => {
+  if (previous === undefined) {
+    Reflect.deleteProperty(process.env, key);
+  } else {
+    process.env[key] = previous;
+  }
+};
+
+// nypm runs the install through tinyexec, which in silent mode drains the
+// child's stdout to completion BEFORE it starts reading stderr. pnpm sends its
+// progress to stdout but floods stderr with Node warnings — on Node 26 the
+// `File descriptor N opened in unmanaged mode` spam alone is thousands of
+// lines. That stderr fills its ~64KB pipe buffer while tinyexec is still busy
+// on stdout, pnpm blocks writing, and the whole install deadlocks (the original
+// "hangs forever" bug). These env vars keep the child quiet on stderr so the
+// buffer never fills:
+//   - NODE_NO_WARNINGS: drop pnpm/corepack's internal Node warnings (the flood).
+//   - COREPACK_ENABLE_DOWNLOAD_PROMPT: never block on corepack's download
+//     confirmation (defensive; corepack already defaults this off for the
+//     `corepack pnpm` entrypoint, but pin it so no path can stall on stdin).
+const withQuietInstallEnv = async <T>(run: () => Promise<T>): Promise<T> => {
+  const prevNodeNoWarnings = process.env.NODE_NO_WARNINGS;
+  const prevDownloadPrompt = process.env.COREPACK_ENABLE_DOWNLOAD_PROMPT;
+
+  process.env.NODE_NO_WARNINGS ??= '1';
+  process.env.COREPACK_ENABLE_DOWNLOAD_PROMPT ??= '0';
+
+  try {
+    return await run();
+  } finally {
+    restoreEnv('NODE_NO_WARNINGS', prevNodeNoWarnings);
+    restoreEnv('COREPACK_ENABLE_DOWNLOAD_PROMPT', prevDownloadPrompt);
+  }
+};
+
 export const installDependencies = async (
   projectDir: string,
   packageManager: PackageManager = 'pnpm',
@@ -12,7 +49,7 @@ export const installDependencies = async (
   );
 
   try {
-    await installDeps({ cwd: projectDir, silent: true, packageManager });
+    await withQuietInstallEnv(() => installDeps({ cwd: projectDir, silent: true, packageManager }));
     spinner.success('Dependencies installed successfully.');
   } catch (error) {
     const message = error instanceof Error ? error.message : 'unknown error';