Environment Management Module

[acreeger]

Port .env file manipulation functionality from bash scripts.

Key Files to Create:

• src/lib/EnvironmentManager.ts
• src/utils/env.ts

Functions to Port:

• setEnvVar() from env-utils.sh
• Port assignment logic (3000 + issue/PR number)
• .env file copying between worktrees

Features:

• Read/write/update .env files
• Set environment variables in target file
• Copy .env files between directories
• Calculate and assign unique ports
• Validate environment configurations

Logging Integration:

• Integrate structured logging using logger utility (see Issue Logging Infrastructure and Output Formatting #27)

Testing Requirements:

• Unit tests for .env file parsing and manipulation
• File system mocking for atomic file operations
• Property-based tests for environment variable validation
• Port calculation tests including conflict detection
• Environment variable validation tests
• Cross-platform file handling tests
• Concurrent access and file locking tests
• Backup and recovery mechanism tests

Acceptance Criteria:

• .env file manipulation works identically to bash scripts verified through regression tests
• Atomic file updates tested with concurrency scenarios
• Port calculation matches existing logic with comprehensive test coverage
• Proper error handling for file operations tested extensively
• File system mock factory working for all scenarios
• Property-based tests revealing no edge cases
• Cross-platform compatibility validated through testing
• Logging integration working

---

Enhancement Summary: Integrated structured logging using logger utility (see Issue #27).

[acreeger]

Research Findings for Issue #4: Environment Management Module

Current Implementation Status

EnvironmentManager.ts (src/lib/EnvironmentManager.ts:1-4)

• Currently exists as a placeholder with no implementation
• Empty class with TODO comment referencing this issue

env.ts (src/utils/env.ts)

• Does not exist yet
• Needs to be created as part of this issue

Bash Script Analysis

env-utils.sh (bash/utils/env-utils.sh:10-52)
The setEnvVar function provides the core functionality to be ported:

1. Function signature: setEnvVar(env_file, var_name, var_value)
2. Key behaviors:
   • Validates required parameters (env_file and var_name)
   • Escapes quotes within values and always wraps values in quotes
   • Handles three scenarios:
     • File doesn't exist: Creates new file with variable
     • Variable doesn't exist in file: Appends to existing file
     • Variable exists: Replaces existing value atomically using temp file
3. Atomic updates: Uses temporary file pattern for safe replacements (lines 32-35)
4. Logging: Uses structured logging with emojis (📝, ✅, ❌)

Important note: The setEnvVar function is defined but not currently used in any of the bash scripts. This suggests it may have been prepared for future use or the scripts have evolved to handle environment variables differently.

Logger Integration

The logger utility was successfully implemented in commit 5880c95 (Issue #27).

Logger Implementation (src/utils/logger.ts:1-116):

• Provides structured logging with emoji prefixes matching bash scripts
• Supports log levels: info (🗂️), success (✅), warn (⚠️), error (❌), debug
• Factory function createLogger() supports custom prefixes, timestamps, and silent mode
• Separates stdout (info/success) and stderr (warn/error) appropriately
• Uses chalk for colored output

Port Assignment Logic

The requirement states "Port assignment logic (3000 + issue/PR number)" but this functionality is not present in the current bash scripts. This appears to be a planned enhancement that should be implemented directly in TypeScript.

Testing Patterns

Based on existing test files (e.g., GitWorktreeManager.test.ts):

• Uses Vitest testing framework
• Mock factories pattern via MockFactories class (src/test-utils/mock-factories.js)
• Comprehensive mocking of external dependencies using vi.mock()
• Clear test structure with describe/it blocks
• BeforeEach hooks for test setup

Dependencies Already Available

From package.json:

• fs-extra: For file operations (already installed)
• chalk: For colored output (already installed, used by logger)
• vitest: Testing framework (configured)
• fast-check: Property-based testing (installed but not yet used)

Implementation Requirements

Based on the issue description and bash script analysis, the implementation needs:

1. Core functionality:

   • Parse and manipulate .env files
   • Atomic file updates with proper error handling
   • Port calculation logic (3000 + issue number)
   • .env file copying between worktrees
   • Environment variable validation

2. Cross-platform considerations:

   • File path handling for Windows/Unix
   • Line ending normalization (CRLF vs LF)
   • File locking mechanisms for concurrent access

3. Integration points:

   • Logger utility for consistent output
   • Mock factories for testing file system operations
   • Property-based testing for validation logic

Key Implementation Decisions Needed

1. File format handling: Should support both quoted and unquoted values, comments, and multi-line values
2. Concurrency: Need file locking strategy for atomic updates when multiple processes access .env files
3. Backup strategy: Consider implementing automatic backup before modifications
4. Validation: Define rules for valid environment variable names and values
5. Error recovery: Rollback mechanism if file operations fail mid-update

Testing Strategy Recommendations

1. Unit tests: Parse/serialize functions, port calculation, validation
2. Integration tests: File I/O with temp directories
3. Property-based tests: Environment variable validation, port conflicts
4. Concurrency tests: Multiple processes writing to same file
5. Regression tests: Compare output with bash script behavior
6. Edge cases: Empty files, malformed content, permission errors

[acreeger]

Implementation Plan for Issue #4: Environment Management Module

1. Type Definitions

File: src/types/environment.ts (new file)

export interface EnvVariable {
  key: string
  value: string
}

export interface EnvFileOptions {
  path: string
  backup?: boolean
  encoding?: BufferEncoding
}

export interface EnvOperationResult {
  success: boolean
  backupPath?: string
  error?: string
}

export interface PortAssignmentOptions {
  basePort?: number // Default: 3000
  issueNumber?: number
  prNumber?: number
}

2. Environment Manager Implementation

File: src/lib/EnvironmentManager.ts (replace placeholder at lines 1-4)

import fs from 'fs-extra'
import path from 'path'
import { logger } from '../utils/logger.js'
import type { EnvVariable, EnvFileOptions, EnvOperationResult, PortAssignmentOptions } from '../types/environment.js'
import { parseEnvFile, formatEnvLine, validateEnvVariable } from '../utils/env.js'

export class EnvironmentManager {
  private readonly lockFile: string = '.env.lock'
  private readonly backupSuffix: string = '.backup'

  /**
   * Set or update an environment variable in a .env file
   * Ports functionality from bash/utils/env-utils.sh:setEnvVar()
   */
  async setEnvVar(filePath: string, key: string, value: string): Promise<EnvOperationResult>

  /**
   * Read and parse a .env file
   */
  async readEnvFile(filePath: string): Promise<Map<string, string>>

  /**
   * Copy .env file from source to destination
   */
  async copyEnvFile(source: string, destination: string, options?: { overwrite?: boolean }): Promise<void>

  /**
   * Calculate unique port for workspace
   * Implements: 3000 + issue/PR number
   */
  calculatePort(options: PortAssignmentOptions): number

  /**
   * Set port environment variable for workspace
   */
  async setPortForWorkspace(envFilePath: string, issueNumber?: number, prNumber?: number): Promise<number>

  /**
   * Validate environment configuration
   */
  async validateEnvFile(filePath: string): Promise<{ valid: boolean; errors: string[] }>

  /**
   * Create atomic file update with backup
   */
  private async atomicFileUpdate(filePath: string, content: string, backup?: boolean): Promise<EnvOperationResult>

  /**
   * Acquire file lock for concurrent access protection
   */
  private async acquireFileLock(filePath: string): Promise<() => Promise<void>>

  /**
   * Create backup of existing file
   */
  private async createBackup(filePath: string): Promise<string>
}

3. Environment Utilities

File: src/utils/env.ts (new file)

import fs from 'fs-extra'
import { logger } from './logger.js'
import type { EnvVariable } from '../types/environment.js'

/**
 * Parse .env file content into key-value map
 * Handles comments, empty lines, quoted/unquoted values, multiline values
 */
export function parseEnvFile(content: string): Map<string, string>

/**
 * Format environment variable as line for .env file
 * Always quotes values and escapes internal quotes
 */
export function formatEnvLine(key: string, value: string): string

/**
 * Validate environment variable name and value
 */
export function validateEnvVariable(key: string, value?: string): { valid: boolean; error?: string }

/**
 * Normalize line endings for cross-platform compatibility
 */
export function normalizeLineEndings(content: string): string

/**
 * Extract port from .env file if present
 */
export function extractPort(envContent: Map<string, string>): number | null

/**
 * Check if environment variable key is valid
 */
export function isValidEnvKey(key: string): boolean

4. Test Implementation

File: src/lib/EnvironmentManager.test.ts (new file)

import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
import { EnvironmentManager } from './EnvironmentManager.js'
import { MockFactories } from '../test-utils/mock-factories.js'
import fs from 'fs-extra'
import path from 'path'
import os from 'os'

vi.mock('fs-extra')

describe('EnvironmentManager', () => {
  describe('setEnvVar', () => {
    // Test: Creates new file if doesn't exist
    // Test: Adds new variable to existing file
    // Test: Updates existing variable
    // Test: Handles concurrent writes with file locking
    // Test: Creates backup on update
    // Test: Handles file permissions errors
    // Test: Validates variable names
    // Test: Escapes quotes in values properly
    // Test: Preserves file formatting and comments
  })

  describe('readEnvFile', () => {
    // Test: Parses simple key=value pairs
    // Test: Handles quoted values
    // Test: Ignores comments and empty lines
    // Test: Handles multiline values
    // Test: Returns empty map for non-existent file
    // Test: Handles malformed lines gracefully
  })

  describe('copyEnvFile', () => {
    // Test: Copies file successfully
    // Test: Throws when source doesn't exist
    // Test: Respects overwrite option
    // Test: Preserves file permissions
    // Test: Handles cross-platform paths
  })

  describe('calculatePort', () => {
    // Test: Returns 3000 + issue number
    // Test: Returns 3000 + PR number when no issue
    // Test: Uses custom base port when provided
    // Test: Returns base port when no issue/PR number
    // Test: Handles edge cases (very large numbers)
  })

  describe('setPortForWorkspace', () => {
    // Test: Sets PORT variable correctly
    // Test: Sets NEXT_PUBLIC_PORT for Next.js projects
    // Test: Updates existing PORT values
    // Test: Returns calculated port value
  })

  describe('validateEnvFile', () => {
    // Test: Validates correct file as valid
    // Test: Reports invalid variable names
    // Test: Reports syntax errors
    // Test: Handles empty files
  })
})

File: src/utils/env.test.ts (new file)

import { describe, it, expect } from 'vitest'
import { parseEnvFile, formatEnvLine, validateEnvVariable, normalizeLineEndings, extractPort, isValidEnvKey } from './env.js'

describe('env utilities', () => {
  describe('parseEnvFile', () => {
    // Test: Parses basic KEY=value format
    // Test: Handles KEY="quoted value" format
    // Test: Handles KEY='single quoted value' format
    // Test: Ignores comments starting with #
    // Test: Handles empty lines
    // Test: Preserves spaces in quoted values
    // Test: Handles escaped quotes in values
    // Test: Parses export KEY=value format
  })

  describe('formatEnvLine', () => {
    // Test: Always quotes values
    // Test: Escapes quotes within values
    // Test: Handles empty values
    // Test: Handles special characters
  })

  describe('validateEnvVariable', () => {
    // Test: Accepts valid variable names (letters, numbers, underscore)
    // Test: Rejects names starting with numbers
    // Test: Rejects names with special characters
    // Test: Accepts any string value
    // Test: Handles empty/null values
  })

  describe('normalizeLineEndings', () => {
    // Test: Converts CRLF to LF
    // Test: Preserves existing LF
    // Test: Handles mixed line endings
  })

  describe('extractPort', () => {
    // Test: Extracts PORT value
    // Test: Returns null when PORT not present
    // Test: Parses numeric strings
    // Test: Handles invalid port values
  })

  describe('isValidEnvKey', () => {
    // Test: Validates standard names
    // Test: Rejects invalid characters
    // Test: Rejects reserved keywords
  })
})

5. Mock Factory Updates

File: src/test-utils/mock-factories.ts (extend MockFileSystem class at line 340)
Add the following methods to the MockFileSystem class:

  setupEnvFile(path: string, variables: Record<string, string>): void {
    const content = Object.entries(variables)
      .map(([key, value]) => `${key}="${value}"`)
      .join('\n')
    this.files.set(path, content)
  }

  mockPathExists(path: string): ReturnType<typeof vi.fn> {
    return vi.fn().mockResolvedValue(this.files.has(path) || this.directories.has(path))
  }

  mockCopyFile(): ReturnType<typeof vi.fn> {
    return vi.fn().mockImplementation((src: string, dest: string) => {
      const content = this.files.get(src)
      if (!content) throw new Error(`Source file ${src} not found`)
      this.files.set(dest, content)
      return Promise.resolve()
    })
  }

  getFileContent(path: string): string | undefined {
    return this.files.get(path)
  }

6. Export Updates

File: src/types/index.ts (add at line 122)

// Environment management types
export * from './environment.js'

7. Property-Based Testing

File: src/lib/EnvironmentManager.property.test.ts (new file)

import { describe, it, expect } from 'vitest'
import fc from 'fast-check'
import { EnvironmentManager } from './EnvironmentManager.js'
import { validateEnvVariable } from '../utils/env.js'
import os from 'os'
import path from 'path'
import fs from 'fs-extra'

describe('EnvironmentManager property tests', () => {
  describe('setEnvVar properties', () => {
    it('should handle any valid key-value pair', async () => {
      await fc.assert(
        fc.asyncProperty(
          fc.string().filter(s => /^[A-Z_][A-Z0-9_]*$/i.test(s)), // Valid env keys
          fc.string(), // Any string value
          async (key, value) => {
            // Test property: Any valid key-value can be set and retrieved
          }
        )
      )
    })

    it('should maintain file integrity under concurrent writes', async () => {
      // Test property: Concurrent writes don't corrupt file
    })
  })

  describe('calculatePort properties', () => {
    it('should always return valid port numbers', () => {
      fc.assert(
        fc.property(
          fc.integer({ min: 1, max: 9999 }),
          (issueNumber) => {
            // Test property: Port is always in valid range (1-65535)
          }
        )
      )
    })

    it('should never have collisions for different issues', () => {
      // Test property: Different issue numbers always produce different ports
    })
  })

  describe('validation properties', () => {
    it('should correctly identify valid/invalid variable names', () => {
      // Test property: Validation matches regex pattern
    })
  })
})

8. Integration Tests

File: src/lib/EnvironmentManager.integration.test.ts (new file)

import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import { EnvironmentManager } from './EnvironmentManager.js'
import fs from 'fs-extra'
import path from 'path'
import os from 'os'

describe('EnvironmentManager integration', () => {
  let testDir: string
  let manager: EnvironmentManager

  beforeEach(async () => {
    testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'env-test-'))
    manager = new EnvironmentManager()
  })

  afterEach(async () => {
    await fs.remove(testDir)
  })

  describe('full workflow', () => {
    it('should handle complete workspace environment setup', async () => {
      // Test: Create .env, set multiple variables, copy to new location, validate
    })

    it('should handle concurrent modifications safely', async () => {
      // Test: Multiple processes writing to same file
    })

    it('should recover from interrupted operations', async () => {
      // Test: Backup restoration after failure
    })
  })

  describe('bash script parity', () => {
    it('should produce identical output to setEnvVar bash function', async () => {
      // Test: Compare with bash script behavior
    })
  })
})

Implementation Order

1. Create type definitions (src/types/environment.ts)
2. Implement env utilities (src/utils/env.ts) with tests (src/utils/env.test.ts)
3. Update MockFileSystem in mock-factories.ts with new helper methods
4. Implement EnvironmentManager class (src/lib/EnvironmentManager.ts)
5. Write unit tests (src/lib/EnvironmentManager.test.ts)
6. Add property-based tests (src/lib/EnvironmentManager.property.test.ts)
7. Write integration tests (src/lib/EnvironmentManager.integration.test.ts)
8. Update exports in src/types/index.ts

Key Implementation Details

File Locking Strategy

Use fs-extra's built-in atomic write operations and implement a simple lock file mechanism:

• Create .env.lock file before modifications
• Use exclusive flag (wx) to prevent race conditions
• Clean up lock file after operation
• Implement timeout for lock acquisition

Atomic Updates

Follow the bash script pattern:

1. Read existing file
2. Create temporary file with new content
3. Move temporary file to replace original (atomic operation)
4. Keep backup if requested

Port Calculation

calculatePort(options: PortAssignmentOptions): number {
  const basePort = options.basePort ?? 3000
  const offset = options.issueNumber ?? options.prNumber ?? 0
  const port = basePort + offset

  // Ensure port is in valid range (1-65535)
  if (port > 65535) {
    throw new Error(`Calculated port ${port} exceeds maximum (65535)`)
  }

  return port
}

Cross-Platform Compatibility

• Use path.join() for all path operations
• Normalize line endings to LF before writing
• Handle both forward and backward slashes in paths
• Test on Windows, macOS, and Linux environments

Error Handling

• Wrap all file operations in try-catch blocks
• Provide descriptive error messages with context
• Use logger for all operations (matching bash script patterns)
• Implement rollback mechanism for failed operations

Logging Integration

Use the existing logger utility with appropriate log levels:

• logger.info() for starting operations
• logger.success() for successful completions
• logger.error() for failures
• logger.debug() for detailed operation steps

Testing Strategy

Unit Tests (>95% coverage)

• Mock all file system operations
• Test each method in isolation
• Cover all error cases
• Verify logging calls

Property-Based Tests

• Use fast-check to discover edge cases
• Test invariants (e.g., port uniqueness)
• Validate input sanitization
• Test concurrent access patterns

Integration Tests

• Use real file system with temp directories
• Test complete workflows
• Verify bash script compatibility
• Test recovery mechanisms

Regression Tests

• Compare output with bash setEnvVar function
• Ensure identical .env file formatting
• Validate port calculation matches specification