fix(cli): use writeEnv for channel link and keep existing values on empty

`catalyst channel link` inlined its own .env.local dump instead of going
through writeEnv, so it skipped the .env.example ordering/comments and
overwrote the file rather than reconciling it. Route it through writeEnv
like `channel create --link`.

Also stop empty CLI-supplied values from clobbering existing on-disk
values: the channel init API returns blank placeholders for keys it does
not own (e.g. MAKESWIFT_SITE_API_KEY), which were wiping the user's real
value on re-run. An empty supplied value now falls back to the existing
.env.local value.

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

Author: jorgemoya

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

@@ -2,8 +2,6 @@ import { select } from '@inquirer/prompts';
 import { Command, InvalidArgumentError, Option } from 'commander';
 import type Conf from 'conf';
 import { colorize } from 'consola/utils';
-import { outputFileSync } from 'fs-extra/esm';
-import { join } from 'node:path';
 
 import { runChannelSiteUrlFlow } from '../lib/channel-site-flow';
 import {
@@ -231,12 +229,7 @@ Examples:
 
     // Writes .env.local in the current working directory — `channel link`
     // runs from inside `core/`, the same place `dev`/`build`/`deploy` run.
-    outputFileSync(
-      join(process.cwd(), '.env.local'),
-      `${Object.entries(envVars)
-        .map(([key, value]) => `${key}=${value}`)
-        .join('\n')}\n`,
-    );
+    writeEnv(process.cwd(), envVars);
 
     const label = channelName ? `"${channelName}" (${channelId})` : `${channelId}`;
 

packages/catalyst/src/cli/lib/write-env.spec.ts

@@ -121,6 +121,32 @@ ENABLE_ADMIN_ROUTE=false
     expect(local).toContain('ENABLE_ADMIN_ROUTE=false');
   });
 
+  it('does not clobber an existing value when the CLI supplies an empty placeholder', () => {
+    // The channel init API returns blank placeholders for keys it does not own
+    // (e.g. MAKESWIFT_SITE_API_KEY). Those must not wipe a value the user
+    // already set on disk.
+    writeExample(`# Store hash comment.
+BIGCOMMERCE_STORE_HASH=
+
+# Makeswift comment.
+MAKESWIFT_SITE_API_KEY=
+`);
+    writeLocal(`BIGCOMMERCE_STORE_HASH=old_hash
+MAKESWIFT_SITE_API_KEY=user_makeswift_key
+`);
+
+    writeEnv(projectDir, {
+      BIGCOMMERCE_STORE_HASH: 'new_hash',
+      MAKESWIFT_SITE_API_KEY: '',
+    });
+
+    const local = readLocal();
+
+    expect(local).toContain('BIGCOMMERCE_STORE_HASH=new_hash');
+    // The empty CLI value falls back to the user's existing value.
+    expect(local).toContain('MAKESWIFT_SITE_API_KEY=user_makeswift_key');
+  });
+
   it('reconciles a stale .env.local by inserting a newly documented key in canonical position', () => {
     // The existing file predates ENABLE_ADMIN_ROUTE being documented and also
     // carries an unknown key the user added by hand.

packages/catalyst/src/cli/lib/write-env.ts

@@ -50,9 +50,17 @@ export const writeEnv = (projectDir: string, envVars: Record<string, string>) =>
 
   // CLI-supplied vars win over what's already on disk so a re-run (e.g.
   // `channel link`) updates credentials in place; anything the CLI didn't touch
-  // falls back to the user's existing value.
-  const resolve = (key: string): string | undefined =>
-    key in envVars ? envVars[key] : existingLocal.get(key);
+  // falls back to the user's existing value. An empty CLI value is treated as
+  // "not supplied" — the channel init API returns blank placeholders for keys it
+  // doesn't own (e.g. MAKESWIFT_SITE_API_KEY), and those must not clobber a real
+  // value the user already has on disk.
+  const resolve = (key: string): string | undefined => {
+    if (key in envVars && envVars[key] !== '') {
+      return envVars[key];
+    }
+
+    return existingLocal.get(key);
+  };
 
   // Without a template we can't follow the documented ordering/comments, so fall
   // back to a flat merge that still preserves the user's existing values.