Redesign env var system to use Vite's builtin system

.gitignore

@@ -163,8 +163,6 @@ __pycache__/
 *.pyo
 
 # Virtual environments
-.env*
-!.env*.example
 .venv*
 env*/
 venv*/

AGENTS.md

@@ -39,13 +39,12 @@ Development for the AI engine happens in the `engine/` folder. The frontend call
   - **Development**: `npm run tauri-dev` for desktop dev mode
 
 #### Environment Variables
-- All `VITE_*` variables must be declared in the appropriate example file:
-  - `frontend/config/.env.example` — core, proprietary, and shared vars
-  - `frontend/config/.env.saas.example` — SaaS-only vars
-  - `frontend/config/.env.desktop.example` — desktop (Tauri)-only vars
-- Never use `|| 'hardcoded-fallback'` inline — put defaults in the example files
-- `npm run prep` / `prep:saas` / `prep:desktop` auto-create the env files from examples on first run, and error if any required keys are missing
-- These prep scripts run automatically at the start of all `dev*`, `build*`, and `tauri*` commands
+- Committed `.env` files contain defaults; local overrides go in `.env.local` / `.env.*.local` (gitignored):
+  - `frontend/.env` — core, proprietary, and shared vars
+  - `frontend/.env.saas` — SaaS-only vars
+  - `frontend/.env.desktop` — desktop (Tauri)-only vars
+- All `VITE_*` variables must be declared in one of these committed `.env` files
+- Never use `|| 'hardcoded-fallback'` inline — put defaults in the `.env` files
 - See `frontend/README.md#environment-variables` for full documentation
 
 #### Import Paths - CRITICAL

frontend/.env

@@ -1,4 +1,5 @@
-# Frontend environment variables for core and proprietary builds.
+# Committed defaults for all builds.
+# To override any value, create a .env.local file (gitignored) with your changes.
 
 # API base URL — use / for same-origin (default for web builds)
 VITE_API_BASE_URL=/

frontend/.env.desktop

@@ -1,5 +1,5 @@
-# Frontend environment variables for desktop (Tauri) builds.
-# Layered on top of .env when running in desktop mode.
+# Desktop (Tauri) build defaults. Loaded in addition to .env when running in desktop mode.
+# To override any value, create a .env.desktop.local file (gitignored) with your changes.
 
 # Desktop backend endpoint — leave blank to use VITE_API_BASE_URL from .env
 VITE_DESKTOP_BACKEND_URL=

frontend/.env.saas

@@ -1,5 +1,5 @@
-# Frontend environment variables for SaaS builds.
-# Layered on top of .env when running in SaaS mode.
+# SaaS build defaults. Loaded in addition to .env when running in SaaS mode.
+# To override any value, create a .env.saas.local file (gitignored) with your changes.
 
 # Userback feedback widget — leave blank to disable
 VITE_USERBACK_TOKEN=

frontend/.gitignore

@@ -14,14 +14,7 @@
 
 # misc
 .DS_Store
-.env
-.env.saas
-.env.desktop
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-!.env*.example
+*.local
 
 npm-debug.log*
 yarn-debug.log*

frontend/README.md

@@ -1,11 +1,13 @@
 # Frontend
 ## Environment Variables
 
-The frontend requires environment variables to be set before running. `npm run dev` will create a `.env` file for you automatically on first run using the defaults from `config/.env.example` - for most development work this is all you need.
+The frontend uses Vite's built-in `.env` file convention.
+Committed `.env` files contain sensible defaults where possible, along with documentation for the variable.
+To override any value locally, create the corresponding `.local` file (gitignored):
 
-If you need to configure specific services (Google Drive, Supabase, Stripe, PostHog), edit your local `.env` file. The values in `config/.env.example` show what each variable does and provides sensible defaults where applicable.
-
-For desktop (Tauri) development, `npm run tauri-dev` will additionally create a `.env.desktop` file from `config/.env.desktop.example`.
+- **`.env.local`** — local overrides for base variables
+- **`.env.saas.local`** — local overrides for SaaS variables
+- **`.env.desktop.local`** — local overrides for desktop variables
 
 ## Docker Setup
 
@@ -127,8 +129,8 @@ This will run the gradle runboot command and the tauri dev command concurrently,
 
 > [!NOTE]
 >
-> Desktop builds require additional environment variables. See [Environment Variables](#environment-variables)
-> above - `npm run tauri-dev` will set these up automatically from `config/.env.desktop.example` on first run.
+> Desktop builds use additional environment variables from `.env.desktop`. See [Environment Variables](#environment-variables)
+> above. Override locally with `.env.desktop.local`.
 
 ### Build
 To build a deployment of the Tauri app. Use this command in the `frontend` folder:
@@ -141,5 +143,5 @@ This will bundle the backend and frontend into one executable for each target. T
 
 > [!NOTE]
 >
-> Desktop builds require additional environment variables. See [Environment Variables](#environment-variables)
-> above - `npm run tauri-build` will set these up automatically from `config/.env.desktop.example` on first run.
+> Desktop builds use additional environment variables from `.env.desktop`. See [Environment Variables](#environment-variables)
+> above. Override locally with `.env.desktop.local`.

frontend/package.json

@@ -79,27 +79,25 @@
     "web-vitals": "^5.1.0"
   },
   "scripts": {
-    "prep": "tsx scripts/setup-env.ts && npm run generate-icons",
-    "prep:saas": "tsx scripts/setup-env.ts --saas && npm run generate-icons",
-    "prep:desktop": "tsx scripts/setup-env.ts --desktop && npm run generate-icons",
-    "prep:desktop-build": "node scripts/build-provisioner.mjs && npm run prep:desktop",
+    "prep": "npm run generate-icons",
+    "prep:desktop-build": "node scripts/build-provisioner.mjs && npm run prep",
     "dev": "npm run prep && vite",
     "dev:core": "npm run prep && vite --mode core",
     "dev:proprietary": "npm run prep && vite --mode proprietary",
-    "dev:saas": "npm run prep:saas && vite --mode saas",
-    "dev:desktop": "npm run prep:desktop && vite --mode desktop",
+    "dev:saas": "npm run prep && vite --mode saas",
+    "dev:desktop": "npm run prep && vite --mode desktop",
     "lint": "npm run lint:eslint && npm run lint:cycles",
     "lint:eslint": "eslint --max-warnings=0",
     "lint:cycles": "dpdm src --circular --no-warning --no-tree --exit-code circular:1",
     "build": "npm run prep && vite build",
     "build:core": "npm run prep && vite build --mode core",
     "build:proprietary": "npm run prep && vite build --mode proprietary",
-    "build:saas": "npm run prep:saas && vite build --mode saas",
-    "build:desktop": "npm run prep:desktop && vite build --mode desktop",
+    "build:saas": "npm run prep && vite build --mode saas",
+    "build:desktop": "npm run prep && vite build --mode desktop",
     "preview": "vite preview",
-    "tauri-dev": "npm run prep:desktop && tauri dev --no-watch",
+    "tauri-dev": "npm run prep && tauri dev --no-watch",
     "tauri-build": "npm run prep:desktop-build && tauri build",
-    "_tauri-build-dev": "npm run prep:desktop && tauri build",
+    "_tauri-build-dev": "npm run prep && tauri build",
     "tauri-build-dev": "npm run _tauri-build-dev -- --no-bundle",
     "tauri-build-dev-mac": "npm run _tauri-build-dev -- --bundles app",
     "tauri-build-dev-windows": "npm run _tauri-build-dev -- --bundles nsis",
@@ -110,8 +108,7 @@
     "typecheck:proprietary": "tsc --noEmit --project src/proprietary/tsconfig.json",
     "typecheck:saas": "tsc --noEmit --project src/saas/tsconfig.json",
     "typecheck:desktop": "tsc --noEmit --project src/desktop/tsconfig.json",
-    "typecheck:scripts": "tsc --noEmit --project scripts/tsconfig.json",
-    "typecheck:all": "npm run typecheck:core && npm run typecheck:proprietary && npm run typecheck:saas && npm run typecheck:desktop && npm run typecheck:scripts",
+    "typecheck:all": "npm run typecheck:core && npm run typecheck:proprietary && npm run typecheck:saas && npm run typecheck:desktop",
     "check": "npm run typecheck && npm run lint && npm run test:run",
     "generate-licenses": "node scripts/generate-licenses.js",
     "generate-icons": "node scripts/generate-icons.js",

frontend/scripts/setup-env.ts

@@ -1,88 +0,0 @@
-/**
- * Copies missing env files from their .example templates, and warns about
- * any keys present in the example but not set in the environment.
- * Also warns about any VITE_ vars set in the environment that aren't listed
- * in any example file.
- *
- * Usage:
- *   tsx scripts/setup-env.ts              # checks .env
- *   tsx scripts/setup-env.ts --desktop    # also checks .env.desktop
- *   tsx scripts/setup-env.ts --saas       # also checks .env.saas
- */
-
-import { existsSync, copyFileSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { config, parse } from 'dotenv';
-
-// npm scripts run from the directory containing package.json (frontend/)
-const root = process.cwd();
-const args = process.argv.slice(2);
-const isDesktop = args.includes('--desktop');
-const isSaas = args.includes('--saas');
-
-console.log('setup-env: see frontend/README.md#environment-variables for documentation');
-
-function getExampleKeys(exampleFile: string): string[] {
-  const examplePath = join(root, exampleFile);
-  if (!existsSync(examplePath)) return [];
-  return Object.keys(parse(readFileSync(examplePath, 'utf-8')));
-}
-
-function ensureEnvFile(envFile: string, exampleFile: string): boolean {
-  const envPath = join(root, envFile);
-  const examplePath = join(root, exampleFile);
-
-  if (!existsSync(examplePath)) {
-    console.warn(`setup-env: ${exampleFile} not found, skipping ${envFile}`);
-    return false;
-  }
-
-  if (!existsSync(envPath)) {
-    copyFileSync(examplePath, envPath);
-    console.log(`setup-env: created ${envFile} from ${exampleFile}`);
-  }
-
-  config({ path: envPath });
-
-  const missing = getExampleKeys(exampleFile).filter(k => !(k in process.env));
-
-  if (missing.length > 0) {
-    console.error(
-      `setup-env: ${envFile} is missing keys from ${exampleFile}:\n` +
-      missing.map(k => `  ${k}`).join('\n') +
-      '\n  Add them manually or delete your local file to re-copy from the example.'
-    );
-    return true;
-  }
-
-  return false;
-}
-
-let failed = false;
-failed = ensureEnvFile('.env', 'config/.env.example') || failed;
-
-if (isDesktop) {
-  failed = ensureEnvFile('.env.desktop', 'config/.env.desktop.example') || failed;
-}
-
-if (isSaas) {
-  failed = ensureEnvFile('.env.saas', 'config/.env.saas.example') || failed;
-}
-
-// Warn about any VITE_ vars set in the environment that aren't listed in any example file.
-const allExampleKeys = new Set([
-  ...getExampleKeys('config/.env.example'),
-  ...getExampleKeys('config/.env.desktop.example'),
-  ...getExampleKeys('config/.env.saas.example'),
-]);
-const unknownViteVars = Object.keys(process.env)
-  .filter(k => k.startsWith('VITE_') && !allExampleKeys.has(k));
-if (unknownViteVars.length > 0) {
-  console.warn(
-    'setup-env: the following VITE_ vars are set but not listed in any example file:\n' +
-    unknownViteVars.map(k => `  ${k}`).join('\n') +
-    '\n  Add them to the appropriate config/.env.*.example file if they are required.'
-  );
-}
-
-if (failed) process.exit(1);

frontend/scripts/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../tsconfig.json",
-  "compilerOptions": {
-    "module": "node16",
-    "moduleResolution": "node16",
-    "noEmit": true
-  },
-  "include": ["./**/*.ts"],
-  "exclude": []
-}

frontend/src/core/env.test.ts

@@ -44,15 +44,15 @@ function findViteEnvVars(srcDir: string): Set<string> {
 }
 
 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');
+  it('every VITE_ var used in source is present in a committed .env file', () => {
+    const baseEnv = readFileSync(join(frontendRoot, '.env'), 'utf-8');
+    const desktopEnv = readFileSync(join(frontendRoot, '.env.desktop'), 'utf-8');
+    const saasEnv = readFileSync(join(frontendRoot, '.env.saas'), 'utf-8');
 
-    const exampleKeys = new Set([...parseEnvKeys(baseEnv), ...parseEnvKeys(desktopEnv), ...parseEnvKeys(saasEnv)]);
+    const declaredKeys = 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);
+    const missing = [...sourceVars].filter(v => !declaredKeys.has(v));
+    expect(missing, `Missing from 'frontend/.env' files: ${missing.join(', ')}`).toHaveLength(0);
   });
 });