fix(cli): symlink .env.local to .dev.vars before preview (#2944)

Wrangler reads secrets from .dev.vars, not .env.local. Create a symlink
from .bigcommerce/.dev.vars to .env.local before running
opennextjs-cloudflare preview so the local server has access to
environment variables.

Author: matthewvolk

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

@@ -1,12 +1,19 @@
 import { Command } from 'commander';
 import { execa } from 'execa';
+import { existsSync, lstatSync, symlinkSync } from 'node:fs';
 import { afterEach, beforeAll, beforeEach, expect, test, vi } from 'vitest';
 
 import { consola } from '../lib/logger';
 import { program } from '../program';
 
 import { start } from './start';
 
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(() => false),
+  lstatSync: vi.fn(),
+  symlinkSync: vi.fn(),
+}));
+
 vi.mock('execa', () => ({
   execa: vi.fn(() => Promise.resolve({})),
   __esModule: true,
@@ -44,3 +51,38 @@ test('calls execa with OpenNext production optimized server', async () => {
     }),
   );
 });
+
+test('creates symlink when .env.local exists but .dev.vars does not', async () => {
+  vi.mocked(existsSync).mockImplementation((p) => {
+    if (String(p).endsWith('.env.local')) return true;
+
+    return false;
+  });
+
+  await program.parseAsync(['node', 'catalyst', 'start']);
+
+  expect(symlinkSync).toHaveBeenCalledWith(
+    expect.stringContaining('.env.local'),
+    expect.stringContaining('.dev.vars'),
+  );
+});
+
+test('warns when .dev.vars exists and is not a symlink', async () => {
+  vi.mocked(existsSync).mockReturnValue(true);
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- partial mock
+  vi.mocked(lstatSync).mockReturnValue({
+    isSymbolicLink: () => false,
+  } as ReturnType<typeof lstatSync>);
+
+  await program.parseAsync(['node', 'catalyst', 'start']);
+
+  expect(symlinkSync).not.toHaveBeenCalled();
+});
+
+test('warns when .env.local does not exist', async () => {
+  vi.mocked(existsSync).mockReturnValue(false);
+
+  await program.parseAsync(['node', 'catalyst', 'start']);
+
+  expect(symlinkSync).not.toHaveBeenCalled();
+});

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

@@ -1,12 +1,37 @@
 import { Command } from 'commander';
 import { execa } from 'execa';
-import { join } from 'node:path';
+import { existsSync, lstatSync, symlinkSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { consola } from '../lib/logger';
 
 export const start = new Command('start')
   .description(
     'Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter.',
   )
   .action(async () => {
+    const envLocal = join(process.cwd(), '.env.local');
+    const devVars = join(process.cwd(), '.bigcommerce', '.dev.vars');
+
+    if (existsSync(envLocal)) {
+      if (!existsSync(devVars)) {
+        const target = relative(join(process.cwd(), '.bigcommerce'), envLocal);
+
+        symlinkSync(target, devVars);
+        consola.success('Symlinked .bigcommerce/.dev.vars → .env.local');
+      } else if (!lstatSync(devVars).isSymbolicLink()) {
+        consola.warn(
+          '.bigcommerce/.dev.vars already exists and is not a symlink. ' +
+            'Wrangler will use it instead of .env.local.',
+        );
+      }
+    } else {
+      consola.warn(
+        'No .env.local file found. The preview server may fail without environment variables.\n' +
+          'Create a .env.local file in your project root with the required variables.',
+      );
+    }
+
     await execa(
       'pnpm',
       [