fix(cli): follow .env.example ordering and comments when writing .env.local

writeEnv previously emitted a flat, unordered list of KEY=VALUE pairs,
ignoring core/.env.example — the file that documents every variable with
comments, ordering, and sensible defaults. Generated .env.local files were
therefore inconsistent and undocumented, and channel link/create clobbered
any values the user had already set.

writeEnv now reads the project's own .env.example as the source of truth for
shape. It reproduces the documented ordering and per-key comment blocks,
substitutes CLI-supplied values in place, and leaves documented-but-unsupplied
keys as their example line (blank or default) so users still see what's
expected. CLI-only variables (e.g. access tokens not in .env.example) are
appended in a clearly separated trailing section.

Existing .env.local files are reconciled rather than overwritten: user-set
values are preserved unless the CLI explicitly supplies a new one, and newly
documented keys are added in their canonical position without disturbing the
ordering of unknown keys. Falls back to a flat merge when no .env.example is
present.

Refs LTRAC-974
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jorgemoya

.changeset/write-env-follow-example.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst": patch
+---
+
+The CLI now follows `.env.example` as the source of truth when writing `.env.local`. Generated env files preserve the documented ordering and per-key comment blocks, render documented-but-unsupplied keys as blank/default active keys, and append any CLI-only variables in a clearly separated trailing section. Existing `.env.local` values are reconciled rather than clobbered on re-runs (e.g. `channel link`), so user-set values are preserved while newly documented keys are added in their canonical position.

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

@@ -0,0 +1,183 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { writeEnv } from './write-env';
+
+// A trimmed-down stand-in for core/.env.example: one blank documented key, one
+// documented key with a default value, each with its own leading comment block.
+const EXAMPLE = `# Store hash comment.
+BIGCOMMERCE_STORE_HASH=
+
+# Channel id comment.
+BIGCOMMERCE_CHANNEL_ID=1
+
+# Admin route comment.
+ENABLE_ADMIN_ROUTE=true
+`;
+
+let projectDir: string;
+
+const writeExample = (contents: string) => {
+  writeFileSync(join(projectDir, '.env.example'), contents);
+};
+
+const writeLocal = (contents: string) => {
+  writeFileSync(join(projectDir, '.env.local'), contents);
+};
+
+const readLocal = () => readFileSync(join(projectDir, '.env.local'), 'utf-8');
+
+beforeEach(() => {
+  projectDir = mkdtempSync(join(tmpdir(), 'catalyst-write-env-test-'));
+});
+
+afterEach(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('writeEnv', () => {
+  it('follows .env.example ordering and preserves each key comment block', () => {
+    writeExample(EXAMPLE);
+
+    writeEnv(projectDir, {
+      BIGCOMMERCE_STORE_HASH: 'abc123',
+      BIGCOMMERCE_CHANNEL_ID: '42',
+    });
+
+    expect(readLocal()).toBe(
+      `# Store hash comment.
+BIGCOMMERCE_STORE_HASH=abc123
+
+# Channel id comment.
+BIGCOMMERCE_CHANNEL_ID=42
+
+# Admin route comment.
+ENABLE_ADMIN_ROUTE=true
+`,
+    );
+  });
+
+  it('renders documented keys that were not supplied using the example line', () => {
+    writeExample(EXAMPLE);
+
+    // Only supply the store hash — the other two keep the example's own line, so
+    // the blank placeholder and the `=1` default both survive.
+    writeEnv(projectDir, { BIGCOMMERCE_STORE_HASH: 'abc123' });
+
+    const local = readLocal();
+
+    expect(local).toContain('BIGCOMMERCE_STORE_HASH=abc123');
+    expect(local).toContain('BIGCOMMERCE_CHANNEL_ID=1');
+    expect(local).toContain('ENABLE_ADMIN_ROUTE=true');
+  });
+
+  it('appends keys not present in .env.example in a separated trailing section', () => {
+    writeExample(EXAMPLE);
+
+    writeEnv(projectDir, {
+      BIGCOMMERCE_STORE_HASH: 'abc123',
+      CATALYST_ACCESS_TOKEN: 'tok_secret',
+    });
+
+    expect(readLocal()).toBe(
+      `# Store hash comment.
+BIGCOMMERCE_STORE_HASH=abc123
+
+# Channel id comment.
+BIGCOMMERCE_CHANNEL_ID=1
+
+# Admin route comment.
+ENABLE_ADMIN_ROUTE=true
+
+# Additional variables set by the Catalyst CLI (not in .env.example).
+CATALYST_ACCESS_TOKEN=tok_secret
+`,
+    );
+  });
+
+  it('preserves existing user values that the CLI does not supply on a re-run', () => {
+    writeExample(EXAMPLE);
+    writeLocal(
+      `BIGCOMMERCE_STORE_HASH=old_hash
+BIGCOMMERCE_CHANNEL_ID=7
+ENABLE_ADMIN_ROUTE=false
+`,
+    );
+
+    // Re-link a channel: only the channel-specific keys are supplied.
+    writeEnv(projectDir, {
+      BIGCOMMERCE_STORE_HASH: 'new_hash',
+      BIGCOMMERCE_CHANNEL_ID: '9',
+    });
+
+    const local = readLocal();
+
+    // Supplied keys are updated in place...
+    expect(local).toContain('BIGCOMMERCE_STORE_HASH=new_hash');
+    expect(local).toContain('BIGCOMMERCE_CHANNEL_ID=9');
+    // ...while the user's untouched value is preserved (not reset to default).
+    expect(local).toContain('ENABLE_ADMIN_ROUTE=false');
+  });
+
+  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.
+    writeExample(EXAMPLE);
+    writeLocal(
+      `BIGCOMMERCE_STORE_HASH=abc123
+BIGCOMMERCE_CHANNEL_ID=1
+MY_CUSTOM_KEY=custom_value
+`,
+    );
+
+    writeEnv(projectDir, {});
+
+    expect(readLocal()).toBe(
+      `# Store hash comment.
+BIGCOMMERCE_STORE_HASH=abc123
+
+# Channel id comment.
+BIGCOMMERCE_CHANNEL_ID=1
+
+# Admin route comment.
+ENABLE_ADMIN_ROUTE=true
+
+# Additional variables set by the Catalyst CLI (not in .env.example).
+MY_CUSTOM_KEY=custom_value
+`,
+    );
+  });
+
+  it('preserves the ordering of existing unknown keys ahead of newly supplied ones', () => {
+    writeExample(EXAMPLE);
+    writeLocal(
+      `EXISTING_UNKNOWN_A=a
+EXISTING_UNKNOWN_B=b
+`,
+    );
+
+    writeEnv(projectDir, { NEW_UNKNOWN: 'c' });
+
+    const local = readLocal();
+    const indexA = local.indexOf('EXISTING_UNKNOWN_A=a');
+    const indexB = local.indexOf('EXISTING_UNKNOWN_B=b');
+    const indexNew = local.indexOf('NEW_UNKNOWN=c');
+
+    expect(indexA).toBeGreaterThan(-1);
+    expect(indexB).toBeGreaterThan(indexA);
+    expect(indexNew).toBeGreaterThan(indexB);
+  });
+
+  it('falls back to a flat merge when .env.example is absent', () => {
+    writeLocal(`EXISTING=keep\n`);
+
+    writeEnv(projectDir, { SUPPLIED: 'value' });
+
+    const local = readLocal();
+
+    expect(local).toContain('EXISTING=keep');
+    expect(local).toContain('SUPPLIED=value');
+  });
+});

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

@@ -1,14 +1,116 @@
 import { outputFileSync } from 'fs-extra/esm';
-import { join } from 'path';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Matches an "active" env assignment — `KEY=VALUE` that isn't commented out.
+// The value is captured greedily (and may be empty) so blank documented keys
+// like `KEY=` still parse and `KEY=a=b` keeps the full value.
+const ACTIVE_KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+
+const keyFromLine = (line: string): string | null => {
+  const match = ACTIVE_KEY_LINE.exec(line);
+
+  return match ? match[1] : null;
+};
+
+// Parse a .env-style body into an ordered KEY -> VALUE map, skipping comments
+// and blank lines. Last assignment wins, matching dotenv semantics.
+const parseEnvValues = (contents: string): Map<string, string> => {
+  const values = new Map<string, string>();
+
+  contents.split('\n').forEach((line) => {
+    const match = ACTIVE_KEY_LINE.exec(line);
+
+    if (match) {
+      values.set(match[1], match[2]);
+    }
+  });
+
+  return values;
+};
 
 // Writes .env.local at the project root — Next.js (and all the catalyst CLI
 // commands) read env vars from there, since the extracted project is the package
 // they run inside.
+//
+// `.env.example` (shipped with the scaffolded project) is the source of truth
+// for shape: the generated `.env.local` mirrors its ordering and per-key comment
+// blocks so the file stays self-documenting. Values supplied by the CLI are
+// substituted in place; documented keys we weren't given keep the example's own
+// line (blank or default) so the user still sees what's expected. Any existing
+// `.env.local` is reconciled rather than clobbered — the user's current values
+// are preserved unless the CLI is explicitly supplying a new one.
 export const writeEnv = (projectDir: string, envVars: Record<string, string>) => {
-  outputFileSync(
-    join(projectDir, '.env.local'),
-    `${Object.entries(envVars)
-      .map(([key, value]) => `${key}=${value}`)
-      .join('\n')}\n`,
-  );
+  const examplePath = join(projectDir, '.env.example');
+  const localPath = join(projectDir, '.env.local');
+
+  const existingLocal = existsSync(localPath)
+    ? parseEnvValues(readFileSync(localPath, 'utf-8'))
+    : new Map<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);
+
+  // 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.
+  if (!existsSync(examplePath)) {
+    const keys = [...new Set([...existingLocal.keys(), ...Object.keys(envVars)])];
+
+    outputFileSync(localPath, `${keys.map((key) => `${key}=${resolve(key) ?? ''}`).join('\n')}\n`);
+
+    return;
+  }
+
+  // Drop a single trailing newline before splitting so we don't reproduce a
+  // spurious blank line; the final `join` re-adds exactly one.
+  const exampleLines = readFileSync(examplePath, 'utf-8').replace(/\n$/, '').split('\n');
+  const exampleKeys = new Set<string>();
+
+  const lines = exampleLines.map((line) => {
+    const key = keyFromLine(line);
+
+    // Comments and blank lines are copied verbatim, preserving each key's
+    // leading comment block.
+    if (key === null) {
+      return line;
+    }
+
+    exampleKeys.add(key);
+
+    const value = resolve(key);
+
+    // Documented keys without a value keep the example's own line so defaults
+    // (e.g. `BIGCOMMERCE_CHANNEL_ID=1`) and blank placeholders survive.
+    return value === undefined ? line : `${key}=${value}`;
+  });
+
+  // Keys the CLI supplied — or the user already had — that the template doesn't
+  // document get appended in a clearly separated section, preserving the order
+  // they were first seen (existing keys first, then newly supplied ones).
+  const extraKeys: string[] = [];
+
+  [...existingLocal.keys()].forEach((key) => {
+    if (!exampleKeys.has(key)) {
+      extraKeys.push(key);
+    }
+  });
+
+  Object.keys(envVars).forEach((key) => {
+    if (!exampleKeys.has(key) && !extraKeys.includes(key)) {
+      extraKeys.push(key);
+    }
+  });
+
+  if (extraKeys.length > 0) {
+    lines.push('', '# Additional variables set by the Catalyst CLI (not in .env.example).');
+
+    extraKeys.forEach((key) => {
+      lines.push(`${key}=${resolve(key) ?? ''}`);
+    });
+  }
+
+  outputFileSync(localPath, `${lines.join('\n')}\n`);
 };