feat(gateway): add support for .env file parsing and integration with environment variable classification

* feat(gateway): add support for .env file parsing and integration with environment variable classification

* feat(dev): enhance .env file handling and improve logging for development server

* feat(docs): update README to reflect CLI hot reload capabilities and env file handling

Author: olamide226

cli/src/commands/dev.ts

@@ -7,7 +7,6 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawn } from 'child_process';
-import * as dotenv from 'dotenv';
 
 /**
  * Get the default path to the bundled gateway binary.
@@ -24,20 +23,20 @@ function findGatewayBinary(specifiedPath?: string): string {
   if (specifiedPath) {
     return specifiedPath;
   }
-  
+
   // Check bundled location first
   const bundledPath = getBundledGatewayPath();
   if (fs.existsSync(bundledPath)) {
     return bundledPath;
   }
-  
+
   // Fall back to PATH
   return 'rep-gateway';
 }
 
 export function createDevCommand(): Command {
   const cmd = new Command('dev');
-  
+
   cmd
     .description('Run local development server with REP gateway')
     .option('-e, --env <path>', 'Path to .env file', '.env.local')
@@ -49,26 +48,23 @@ export function createDevCommand(): Command {
     .action(async (options) => {
       try {
         console.log(chalk.blue('Starting REP development server...\n'));
-        
-        // Load environment variables from .env file
+
         const envPath = options.env;
-        if (fs.existsSync(envPath)) {
-          console.log(chalk.gray(`Loading environment from: ${envPath}`));
-          const result = dotenv.config({ path: envPath });
-          if (result.error) {
-            throw new Error(`Failed to load .env file: ${result.error.message}`);
-          }
-          console.log(chalk.gray(`Loaded ${Object.keys(result.parsed || {}).length} variable(s)\n`));
+        const envFileExists = fs.existsSync(envPath);
+        const absEnvPath = envFileExists ? path.resolve(envPath) : '';
+
+        if (envFileExists) {
+          console.log(chalk.gray(`Using environment file: ${absEnvPath}`));
         } else {
-          console.log(chalk.yellow(`⚠ Environment file not found: ${envPath}`));
+          console.log(chalk.yellow(`Warning: Environment file not found: ${envPath}`));
           console.log(chalk.gray('Continuing with system environment variables\n'));
         }
-        
+
         // Build gateway arguments
         const args: string[] = [];
-        
+
         args.push('--port', options.port);
-        
+
         if (options.proxy) {
           args.push('--mode', 'proxy');
           args.push('--upstream', options.proxy);
@@ -78,14 +74,26 @@ export function createDevCommand(): Command {
         } else {
           throw new Error('Either --proxy or --static must be specified');
         }
-        
+
         if (options.hotReload) {
           args.push('--hot-reload');
         }
-        
+
+        // Pass the env file to the gateway so it reads it directly.
+        // When hot reload is enabled, also configure file_watch mode
+        // so the gateway re-reads the file on changes without a restart.
+        if (absEnvPath) {
+          args.push('--env-file', absEnvPath);
+
+          if (options.hotReload) {
+            args.push('--hot-reload-mode', 'file_watch');
+            args.push('--watch-path', absEnvPath);
+          }
+        }
+
         // Find gateway binary
         const gatewayBin = findGatewayBinary(options.gatewayBin);
-        
+
         // Log configuration
         console.log(chalk.blue('Configuration:'));
         console.log(chalk.gray(`  Gateway binary: ${gatewayBin}`));
@@ -98,55 +106,58 @@ export function createDevCommand(): Command {
           console.log(chalk.gray(`  Static dir: ${options.static}`));
         }
         console.log(chalk.gray(`  Hot reload: ${options.hotReload ? 'enabled' : 'disabled'}`));
+        if (options.hotReload && absEnvPath) {
+          console.log(chalk.gray(`  Watching: ${absEnvPath}`));
+        }
         console.log('');
-        
+
         // Spawn the gateway process
         console.log(chalk.blue(`Starting gateway: ${gatewayBin} ${args.join(' ')}\n`));
-        
+
         const gateway = spawn(gatewayBin, args, {
           stdio: 'inherit',
           env: process.env,
         });
-        
+
         // Handle gateway exit
         gateway.on('error', (err) => {
-          console.error(chalk.red('\n✗ Failed to start gateway'));
+          console.error(chalk.red('\nFailed to start gateway'));
           console.error(chalk.red(`Error: ${err.message}`));
           console.error(chalk.gray('\nTroubleshooting:'));
           console.error(chalk.gray('  - Ensure rep-gateway is installed and in PATH'));
           console.error(chalk.gray('  - Or specify the binary path with --gateway-bin'));
           console.error(chalk.gray('  - Build the gateway: cd gateway && make build'));
           process.exit(1);
         });
-        
+
         gateway.on('exit', (code, signal) => {
           if (signal) {
-            console.log(chalk.yellow(`\n⚠ Gateway terminated by signal: ${signal}`));
+            console.log(chalk.yellow(`\nGateway terminated by signal: ${signal}`));
           } else if (code !== 0) {
-            console.error(chalk.red(`\n✗ Gateway exited with code: ${code}`));
+            console.error(chalk.red(`\nGateway exited with code: ${code}`));
             process.exit(code || 1);
           } else {
             console.log(chalk.gray('\nGateway stopped'));
           }
           process.exit(code || 0);
         });
-        
+
         // Handle Ctrl+C
         process.on('SIGINT', () => {
           console.log(chalk.gray('\n\nShutting down...'));
           gateway.kill('SIGINT');
         });
-        
+
         process.on('SIGTERM', () => {
           gateway.kill('SIGTERM');
         });
-        
+
       } catch (err) {
-        console.error(chalk.red('✗ Dev server failed'));
+        console.error(chalk.red('Dev server failed'));
         console.error(chalk.red(err instanceof Error ? err.message : String(err)));
         process.exit(1);
       }
     });
-  
+
   return cmd;
 }

examples/todo-react/README.md

@@ -143,9 +143,10 @@ pnpm rep:dev
 pnpm rep:serve
 ```
 
-The CLI reads `.env.local`, strips comments, exports every `REP_*` var into
-the spawned gateway's environment, and passes the right `--mode`, `--upstream`,
-and `--static-dir` flags automatically.
+The CLI passes `--env-file .env.local` to the gateway so it reads the file
+directly. With `--hot-reload`, the CLI also sets `--hot-reload-mode file_watch`
+and `--watch-path` automatically — edit `.env.local` and the gateway picks up
+changes live via SSE, no restart needed.
 
 ---
 
@@ -253,55 +254,58 @@ The gateway exposes a Server-Sent Events endpoint at `/rep/changes`. The SDK
 connects to it lazily when any `useRep()` hook mounts, and re-renders
 subscribed components when a change event arrives.
 
-**Start the gateway with hot reload enabled:**
+#### Using the CLI (recommended)
+
+The `rep:dev` and `rep:serve` scripts already pass `--hot-reload`, which
+automatically sets up file watching on `.env.local`:
 
 ```bash
-REP_PUBLIC_APP_TITLE="REP Todo" \
-REP_PUBLIC_ENV_NAME=development \
-REP_PUBLIC_API_URL=http://localhost:3001 \
-REP_PUBLIC_MAX_TODOS=5 \
-REP_SENSITIVE_ANALYTICS_KEY=ak_demo_abc123 \
-./gateway/bin/rep-gateway \
-  --mode embedded \
-  --static-dir examples/todo-react/dist \
-  --hot-reload
+pnpm rep:serve
 ```
 
-Open `http://localhost:8080` and click **Show Config**. Observe the SSE
-connection in the Network tab (`/rep/changes`, type: `eventsource`).
+Open `http://localhost:8080`, then edit `.env.local` — for example, change
+`REP_PUBLIC_APP_TITLE=REP Todo` to `REP_PUBLIC_APP_TITLE=My Todos`. The
+gateway detects the file change, re-reads it, and pushes updates via SSE.
+The browser updates without a page reload.
 
-**Trigger a reload — no rebuild, no page refresh:**
+#### Using the gateway directly
 
-In a second terminal, send `SIGHUP` to the gateway process. It re-reads
-`os.Environ()`, rebuilds the payload, and broadcasts diffs over SSE:
+Use `--env-file` to point the gateway at a `.env` file, and `--hot-reload-mode
+file_watch` with `--watch-path` to watch it for changes:
 
 ```bash
-kill -HUP $(pgrep rep-gateway)
+./gateway/bin/rep-gateway \
+  --mode embedded \
+  --static-dir examples/todo-react/dist \
+  --env-file .env.local \
+  --hot-reload \
+  --hot-reload-mode file_watch \
+  --watch-path .env.local
 ```
 
-The connected browser tabs receive the event and `useRep()` hooks re-render
-with the updated values — **no page load**.
+Edit `.env.local` in your editor. The gateway detects the mtime change,
+re-reads the file, rebuilds the payload, and broadcasts diffs over SSE.
+Connected browser tabs re-render — **no page load, no restart**.
 
-**Changing values between restarts (no rebuild):**
+#### Manual signal mode
 
-To see different values, restart the gateway with new env vars — the built
-`dist/` is untouched:
+You can also trigger a reload manually with `SIGHUP` (useful for scripting):
 
 ```bash
-# Ctrl+C the running gateway, then:
-REP_PUBLIC_APP_TITLE="My Todos" \
-REP_PUBLIC_ENV_NAME=staging \
-REP_PUBLIC_MAX_TODOS=3 \
+# Start with signal mode (the default when --env-file is not watched)
+REP_PUBLIC_APP_TITLE="REP Todo" \
+REP_PUBLIC_ENV_NAME=development \
+REP_PUBLIC_API_URL=http://localhost:3001 \
+REP_PUBLIC_MAX_TODOS=5 \
 REP_SENSITIVE_ANALYTICS_KEY=ak_demo_abc123 \
 ./gateway/bin/rep-gateway \
   --mode embedded \
   --static-dir examples/todo-react/dist \
   --hot-reload
-```
 
-The title changes from `REP Todo` to `My Todos`, the badge turns amber
-(`staging`), and the add form locks after 3 todos — all from env vars, all
-without `npm run build`.
+# In another terminal:
+kill -HUP $(pgrep rep-gateway)
+```
 
 > **Production hot reload:** In Kubernetes or Docker Swarm, env vars can be
 > rotated in-flight via ConfigMaps or secrets. The gateway detects the change
@@ -327,7 +331,7 @@ docker run --rm -p 8080:8080 \
   -e REP_PUBLIC_APP_TITLE="REP Todo" \
   -e REP_PUBLIC_ENV_NAME=development \
   -e REP_PUBLIC_API_URL=http://localhost:3001 \
-  -e REP_PUBLIC_MAX_TODOS=5 \
+  -e REP_PUBLIC_MAX_TODOS=55 \
   -e REP_SENSITIVE_ANALYTICS_KEY=ak_demo_abc123 \
   rep-todo
 ```
@@ -400,8 +404,8 @@ variables differ between deployments — exactly like any other twelve-factor ap
 |---|---|---|
 | `pnpm rep:validate` | `rep validate --manifest .rep.yaml` | Validate manifest schema and constraints |
 | `pnpm rep:typegen` | `rep typegen --manifest .rep.yaml --output src/rep.d.ts` | Generate typed SDK overloads |
-| `pnpm rep:dev` | `rep dev --env .env.local --proxy http://localhost:5173` | Dev server (proxy mode) |
-| `pnpm rep:serve` | `rep dev --env .env.local --static ./dist --hot-reload` | Dev server (embedded, hot reload) |
+| `pnpm rep:dev` | `rep dev --env .env.local --proxy http://localhost:5173 --hot-reload` | Dev server (proxy mode, file watching) |
+| `pnpm rep:serve` | `rep dev --env .env.local --static ./dist --hot-reload` | Dev server (embedded, file watching) |
 | `pnpm rep:lint` | `rep lint --dir ./dist` | Scan build output for leaked secrets |
 
 ---

gateway/internal/config/classify.go

@@ -87,23 +87,45 @@ func (cv *ClassifiedVars) ServerMap() map[string]string {
 	return m
 }
 
-// ReadAndClassify reads all environment variables, filters for the REP_ prefix,
+// ReadAndClassify reads environment variables, filters for the REP_ prefix,
 // classifies them, strips prefixes, and validates uniqueness.
 //
+// When envFile is non-empty, the file is parsed first as a base layer.
+// Process environment variables (os.Environ) are then overlaid on top,
+// so real env vars always take precedence over the file.
+//
 // Per REP-RFC-0001 §3.2:
 //   - Only REP_* prefixed variables are read.
 //   - The classification prefix is stripped from the name.
 //   - Names MUST be unique across all tiers after stripping.
-func ReadAndClassify() (*ClassifiedVars, error) {
-	vars := &ClassifiedVars{}
-	seen := make(map[string]string) // name → original key (for collision detection)
+func ReadAndClassify(envFile string) (*ClassifiedVars, error) {
+	// Build a merged map: env file (base) + os.Environ() (override).
+	merged := make(map[string]string)
+
+	if envFile != "" {
+		fileVars, err := ParseEnvFile(envFile)
+		if err != nil {
+			return nil, fmt.Errorf("reading env file: %w", err)
+		}
+		for k, v := range fileVars {
+			merged[k] = v
+		}
+	}
 
+	// Process environment overrides file values.
 	for _, env := range os.Environ() {
 		key, value, ok := strings.Cut(env, "=")
 		if !ok {
 			continue
 		}
+		merged[key] = value
+	}
+
+	// Classify the merged set.
+	vars := &ClassifiedVars{}
+	seen := make(map[string]string) // name → original key (for collision detection)
 
+	for key, value := range merged {
 		// Skip non-REP variables.
 		if !strings.HasPrefix(key, "REP_") {
 			continue
@@ -129,8 +151,6 @@ func ReadAndClassify() (*ClassifiedVars, error) {
 			v.Name = strings.TrimPrefix(key, "REP_SERVER_")
 			v.Tier = TierServer
 		default:
-			// REP_ prefixed but doesn't match a known tier — skip with a warning.
-			// This covers things like REP_CUSTOM_FOO which don't fit the spec.
 			continue
 		}