Add system for managing env vars (#5902)

# Description of Changes
Previously, `VITE_*` environment variables were scattered across the
codebase with hardcoded fallback values inline (e.g.
`import.meta.env.VITE_STRIPE_KEY || 'pk_live_...'`). This made it
unclear which variables
were required, what they were for, and caused real keys to be silently
used in builds where they hadn't been explicitly configured.

## What's changed

I've added `frontend/.env.example` and `frontend/.env.desktop.example`,
which declare every `VITE_*` variable the app uses, with comments
explaining each one and sensible defaults where applicable. These
are the source of truth for what's required.

I've added a setup script which runs before `npm run dev`, `build`,
`tauri-dev`, and all `tauri-build*` commands. It:
- Creates your local `.env` / `.env.desktop` from the example files on
first run, so you don't need to do anything manually
- Errors if you're missing keys that the example defines (e.g. after
pulling changes that added a new variable). These can either be
manually-set env vars, or in your `.env` file (env vars take precedence
over `.env` file vars when running)
- Warns if you have `VITE_*` variables set in your environment that
aren't listed in any example file

I've removed all `|| 'hardcoded-value'` defaults from source files
because they are not necessary in this system, as all variables must be
explicitly set (they can be set to `VITE_ENV_VAR=`, just as long as the
variable actually exists). I think this system will make it really
obvious exactly what you need to set and what's actually running in the
code.

I've added a test that checks that every `import.meta.env.VITE_*`
reference found in source is present in at least one example file, so
new variables can't be added without being documented.

## For contributors

New contributors shouldn't need to do anything - `npm run dev` will
create your `.env` automatically.

If you already have a `.env` file in the `frontend/` folder, you may
well need to update it to make the system happy. Here's an example
output from running `npm run dev` with an old `.env` file:

```
$ npm run dev

> frontend@0.1.0 dev
> npm run prep && vite


> frontend@0.1.0 prep
> tsx scripts/setup-env.ts && npm run generate-icons

setup-env: see frontend/README.md#environment-variables for documentation
setup-env: .env is missing keys from config/.env.example:
  VITE_GOOGLE_DRIVE_CLIENT_ID
  VITE_GOOGLE_DRIVE_API_KEY
  VITE_GOOGLE_DRIVE_APP_ID
  VITE_PUBLIC_POSTHOG_KEY
  VITE_PUBLIC_POSTHOG_HOST
  Add them manually or delete your local file to re-copy from the example.
setup-env: the following VITE_ vars are set but not listed in any example file:
  VITE_DEV_BYPASS_AUTH
  Add them to config/.env.example or config/.env.desktop.example if they are required.
```

If you add a new `VITE_*` variable to the codebase, add it to the
appropriate `frontend/config/.env.example` file or the test will fail.

frontend/src/core/env.test.ts

@@ -0,0 +1,58 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+import { fileURLToPath } from 'url';
+import { describe, it, expect } from 'vitest';
+
+// frontend/ root — this file lives at src/core/env.test.ts
+const frontendRoot = join(fileURLToPath(import.meta.url), '../../..');
+
+function parseEnvKeys(content: string): Set<string> {
+  const keys = new Set<string>();
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#')) {
+      const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=/);
+      if (match) keys.add(match[1]);
+    }
+  }
+  return keys;
+}
+
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory() && entry !== 'node_modules' && entry !== 'assets') {
+      files.push(...collectSourceFiles(fullPath));
+    } else if (stat.isFile() && (extname(entry) === '.ts' || extname(entry) === '.tsx') && !entry.endsWith('.d.ts')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function findViteEnvVars(srcDir: string): Set<string> {
+  const vars = new Set<string>();
+  for (const file of collectSourceFiles(srcDir)) {
+    const content = readFileSync(file, 'utf-8');
+    for (const match of content.matchAll(/import\.meta\.env\.(VITE_\w+)/g)) {
+      vars.add(match[1]);
+    }
+  }
+  return vars;
+}
+
+describe('env vars', () => {
+  it('every VITE_ var used in source is present in an example env file', () => {
+    const baseEnv = readFileSync(join(frontendRoot, 'config/.env.example'), 'utf-8');
+    const desktopEnv = readFileSync(join(frontendRoot, 'config/.env.desktop.example'), 'utf-8');
+    const saasEnv = readFileSync(join(frontendRoot, 'config/.env.saas.example'), 'utf-8');
+
+    const exampleKeys = new Set([...parseEnvKeys(baseEnv), ...parseEnvKeys(desktopEnv), ...parseEnvKeys(saasEnv)]);
+    const sourceVars = findViteEnvVars(join(frontendRoot, 'src'));
+
+    const missing = [...sourceVars].filter(v => !exampleKeys.has(v));
+    expect(missing, `Missing from 'frontend/config/.env.example' files: ${missing.join(', ')}`).toHaveLength(0);
+  });
+});

frontend/src/core/services/apiClientConfig.ts

@@ -15,5 +15,5 @@ export function getApiBaseUrl(): string {
     return (window as any).STIRLING_PDF_API_BASE_URL;
   }
 
-  return import.meta.env.VITE_API_BASE_URL || '/';
+  return import.meta.env.VITE_API_BASE_URL;
 }

frontend/src/core/services/supabaseClient.ts

@@ -1,7 +1,7 @@
 import { createClient, SupabaseClient } from '@supabase/supabase-js';
 
-const supabaseUrl = import.meta.env.VITE_SUPABASE_URL || 'https://rficokptxxxxtyzcvgmx.supabase.co';
-const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb';
+const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
+const supabaseAnonKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY;
 
 // Check if Supabase is configured
 export const isSupabaseConfigured = !!(supabaseUrl && supabaseAnonKey);

frontend/src/desktop/constants/connection.ts

@@ -2,22 +2,14 @@
  * Connection-related constants for desktop app
  */
 
-// SaaS server URL from environment variable
-// The SaaS authentication server (Supabase)
-export const STIRLING_SAAS_URL: string = import.meta.env.VITE_SAAS_SERVER_URL || '';
+// SaaS authentication server URL
+export const STIRLING_SAAS_URL: string = import.meta.env.VITE_SAAS_SERVER_URL;
 
-// SaaS backend API URL from environment variable
-// The Stirling SaaS backend API server (for team endpoints, etc.)
-export const STIRLING_SAAS_BACKEND_API_URL: string = import.meta.env.VITE_SAAS_BACKEND_API_URL || '';
+// Stirling SaaS backend API server (for team endpoints, etc.)
+export const STIRLING_SAAS_BACKEND_API_URL: string = import.meta.env.VITE_SAAS_BACKEND_API_URL;
 
-// Supabase publishable key from environment variable
-// Used for SaaS authentication
-export const SUPABASE_KEY: string = import.meta.env.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb';
+// Supabase publishable key — used for SaaS authentication
+export const SUPABASE_KEY: string = import.meta.env.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY;
 
 // Desktop deep link callback for Supabase email confirmations
 export const DESKTOP_DEEP_LINK_CALLBACK = 'stirlingpdf://auth/callback';
-
-// Validation warnings
-if (!STIRLING_SAAS_BACKEND_API_URL) {
-  console.warn('[Desktop Connection] VITE_SAAS_BACKEND_API_URL not configured - SaaS backend APIs (teams, etc.) will not work');
-}

frontend/src/desktop/hooks/useEndpointConfig.ts

@@ -401,8 +401,7 @@ export function useMultipleEndpointsEnabled(endpoints: string[]): {
 // Default backend URL from environment variables
 const DEFAULT_BACKEND_URL =
   import.meta.env.VITE_DESKTOP_BACKEND_URL
-  || import.meta.env.VITE_API_BASE_URL
-  || '';
+  || import.meta.env.VITE_API_BASE_URL;
 
 /**
  * Desktop override exposing the backend URL based on connection mode.

frontend/src/desktop/services/apiClientConfig.ts

@@ -19,7 +19,7 @@ export function getApiBaseUrl(): string {
       return (window as any).STIRLING_PDF_API_BASE_URL;
     }
 
-    return import.meta.env.VITE_API_BASE_URL || '/';
+    return import.meta.env.VITE_API_BASE_URL;
   }
 
   // In Tauri mode, return empty string as placeholder

frontend/src/index.tsx

@@ -12,8 +12,8 @@ import posthog from 'posthog-js';
 import { PostHogProvider } from '@posthog/react';
 import { BASE_PATH } from '@app/constants/app';
 
-posthog.init('phc_VOdeYnlevc2T63m3myFGjeBlRcIusRgmhfx6XL5a1iz', {
-  api_host: 'https://eu.i.posthog.com',
+posthog.init(import.meta.env.VITE_PUBLIC_POSTHOG_KEY, {
+  api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
   defaults: '2025-05-24',
   capture_exceptions: true, // This enables capturing exceptions using Error Tracking, set to false if you don't want this
   debug: false,

frontend/src/proprietary/components/shared/stripeCheckout/StripeCheckout.tsx

@@ -19,7 +19,7 @@ import { SuccessStage } from '@app/components/shared/stripeCheckout/stages/Succe
 import { ErrorStage } from '@app/components/shared/stripeCheckout/stages/ErrorStage';
 
 // Validate Stripe key (static validation, no dynamic imports)
-const STRIPE_KEY = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY || 'pk_live_51Q56W2P9mY5IAnSnp3kcxG50uyFMLuhM4fFs774DAP3t88KmlwUrUo31CecpnAZ9FHsNp8xJyOnYNYNVVP6z4oi500q5sFYPEp';
+const STRIPE_KEY = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY;
 
 if (!STRIPE_KEY) {
   console.error(

frontend/src/proprietary/components/shared/stripeCheckout/stages/PaymentStage.tsx

@@ -6,7 +6,7 @@ import { EmbeddedCheckoutProvider, EmbeddedCheckout } from '@stripe/react-stripe
 import { PlanTier } from '@app/services/licenseService';
 
 // Load Stripe once
-const STRIPE_KEY = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY || 'pk_live_51Q56W2P9mY5IAnSnp3kcxG50uyFMLuhM4fFs774DAP3t88KmlwUrUo31CecpnAZ9FHsNp8xJyOnYNYNVVP6z4oi500q5sFYPEp';
+const STRIPE_KEY = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY;
 const stripePromise = STRIPE_KEY ? loadStripe(STRIPE_KEY) : null;
 
 interface PaymentStageProps {

frontend/src/proprietary/utils/protocolDetection.ts

@@ -9,7 +9,7 @@
  * @returns true if key exists and has valid format
  */
 export function isStripeConfigured(): boolean {
-  const stripeKey = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY || 'pk_live_51Q56W2P9mY5IAnSnp3kcxG50uyFMLuhM4fFs774DAP3t88KmlwUrUo31CecpnAZ9FHsNp8xJyOnYNYNVVP6z4oi500q5sFYPEp';
+  const stripeKey = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY;
   return !!stripeKey && stripeKey.startsWith('pk_');
 }
 

frontend/src/saas/components/shared/StripeCheckoutSaas.tsx

@@ -6,7 +6,7 @@ import { EmbeddedCheckoutProvider, EmbeddedCheckout } from '@stripe/react-stripe
 import { supabase } from '@app/auth/supabase';
 import { Z_INDEX_OVER_SETTINGS_MODAL } from '@app/styles/zIndex';
 
-const stripePromise = loadStripe(import.meta.env.VITE_STRIPE_PUBLISHABLE_DEFAULT_KEY);
+const stripePromise = loadStripe(import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY);
 
 export type PurchaseType = 'subscription' | 'credits';
 export type CreditsPack = 'xsmall' | 'small' | 'medium' | 'large' | null;

frontend/src/saas/services/apiClient.ts

@@ -31,7 +31,7 @@ function decodeJwtPayload(token: string): Record<string, unknown> | null {
 
 // Create axios instance with default config
 const apiClient = axios.create({
-  baseURL: import.meta.env.VITE_API_BASE_URL || '/', // Use env var or relative path (proxied by Vite in dev)
+  baseURL: import.meta.env.VITE_API_BASE_URL,
   responseType: 'json',
 });
 

frontend/src/saas/utils/pathUtils.ts

@@ -1,6 +1,6 @@
 import { URL_TO_TOOL_MAP } from '@app/utils/urlMapping'
 
-const SUBPATH = (import.meta.env.VITE_RUN_SUBPATH || '').replace(/^\/|\/$/g, '') // "app" or ""
+const SUBPATH = import.meta.env.VITE_RUN_SUBPATH.replace(/^\/|\/$/g, '') // "app" or ""
 
 /**
  * Normalize pathname by stripping subpath prefix and trailing slashes