Utilities

Overview

The utilities layer provides ~331 subdirectories of utility modules that support the core functionality of the application.

Utility Directory Structure

src/utils/
├── permissions/ - Permission system utilities
├── settings/ - Settings management
├── plugins/ - Plugin system utilities
├── model/ - Model configuration
├── api/ - API utilities
├── git/ - Git operations
├── file/ - File system utilities
├── [331+ utility modules]
└── index.ts - Utility exports

Core Utility Categories

Permissions Utilities (src/utils/permissions/)

// src/utils/permissions/PermissionMode.ts
export const PERMISSION_MODES = {
  DEFAULT: 'default',
  PLAN: 'plan',
  AUTO: 'auto',
  BYPASS: 'bypassPermissions',
} as const;

// src/utils/permissions/permissionSetup.ts
export function initialPermissionModeFromCLI(): PermissionMode {
  // Parse permission mode from CLI flags
}

export function checkAndDisableBypassPermissions(): void {
  // Check and disable bypass permissions if needed
}

export function verifyAutoModeGateAccess(): boolean {
  // Verify auto mode access
}

Settings Utilities (src/utils/settings/)

// src/utils/settings/settings.ts
export function getInitialSettings(): Settings {
  // Get initial settings from config
}

export function getSettingsForSource(source: SettingSource): Settings {
  // Get settings from specific source
}

export function getSettingsWithErrors(): { settings: Settings; errors: ValidationError[] } {
  // Get settings with validation errors
}

// src/utils/settings/mdm/settings.ts
export function ensureMdmSettingsLoaded(): Promise<void> {
  // Ensure MDM settings are loaded
}

Plugin Utilities (src/utils/plugins/)

// src/utils/plugins/pluginLoader.ts
export async function loadAllPluginsCacheOnly(): Promise<PluginLoadResult> {
  // Load plugins from cache
}

export function clearPluginCache(reason: string): void {
  // Clear plugin cache
}

// src/utils/plugins/managedPlugins.ts
export function getManagedPluginNames(): string[] {
  // Get list of managed plugin names
}

Model Utilities (src/utils/model/)

// src/utils/model/model.ts
export function getDefaultMainLoopModel(): string {
  // Get default model for main loop
}

export function parseUserSpecifiedModel(modelString: string): ModelInfo {
  // Parse user-specified model string
}

export function getModelDeprecationWarning(model: string): string | null {
  // Get deprecation warning for model
}

// src/utils/model/modelCapabilities.ts
export function refreshModelCapabilities(): void {
  // Refresh model capabilities cache
}

File System Utilities (src/utils/fsOperations.ts)

export function getFsImplementation(): FsImplementation {
  // Get file system implementation
}

export function safeResolvePath(fs: FsImplementation, path: string): {
  resolvedPath: string;
  exists: boolean;
} {
  // Safely resolve file path
}

Git Utilities (src/utils/git.ts)

export function findGitRoot(cwd: string): string | null {
  // Find git repository root
}

export function getBranch(): string | null {
  // Get current git branch
}

export function getIsGit(): boolean {
  // Check if current directory is a git repo
}

export function getWorktreeCount(): number {
  // Get number of git worktrees
}

Utility Pattern

Utilities follow a consistent pattern:

// Utility function
export function utilityFunction(params: Params): Result {
  // Utility logic
  return result;
}

// Utility class
export class UtilityClass {
  private state: StateType;
  
  initialize(): void {
    // Initialize utility
  }
  
  performOperation(params: Params): Promise<Result> {
    // Perform utility operation
  }
}

Utility Best Practices

1. Pure Functions: Stateless utilities where possible
2. Error Handling: Graceful degradation
3. Caching: Results cached for performance
4. Lazy Loading: Heavy utilities loaded on demand
5. Type Safety: Strict TypeScript typing

Utility Integration

Utilities are imported and used throughout the codebase:

import { getInitialSettings } from './utils/settings/settings.js';
import { findGitRoot } from './utils/git.js';
import { loadAllPluginsCacheOnly } from './utils/plugins/pluginLoader.js';

// Use utilities in components or services
const settings = getInitialSettings();
const gitRoot = findGitRoot(cwd);
const plugins = await loadAllPluginsCacheOnly();

Utility Performance

1. Parallel Loading: Non-blocking utility initialization
2. Caching: Expensive operations cached
3. Lazy Evaluation: Utilities loaded when needed
4. Event-Driven: Utilities emit events for state changes

Utility Security

1. Permission Checks: Utilities respect permission modes
2. Working Directory: Utilities respect cwd restrictions
3. Feature Flags: Conditional utility availability
4. Error Boundaries: Isolated failure handling

Utility Examples

Permission Setup Utility

// src/utils/permissions/permissionSetup.ts
export function initialPermissionModeFromCLI(): PermissionMode {
  const cliArgs = process.argv.slice(2);
  const modeIndex = cliArgs.indexOf('--permission-mode');
  
  if (modeIndex !== -1 && cliArgs[modeIndex + 1]) {
    return cliArgs[modeIndex + 1] as PermissionMode;
  }
  return 'default';
}

export function checkAndDisableBypassPermissions(): void {
  // Check if bypass permissions should be disabled
  // Update settings accordingly
}

Settings Management Utility

// src/utils/settings/settings.ts
export function getInitialSettings(): Settings {
  // Load settings from settings.json or environment
  const settingsPath = getSettingsPath();
  const settings = loadSettingsFromFile(settingsPath);
  return settings;
}

export function getSettingsForSource(source: SettingSource): Settings {
  // Filter settings by source (user, policy, etc.)
  return settings.filter(s => s.source === source);
}

Utility Documentation

Each utility has inline documentation:

/**
 * findGitRoot - Find git repository root
 * 
 * @param cwd - Current working directory
 * @returns Git root path or null if not found
 */
export function findGitRoot(cwd: string): string | null {
  // Implementation
}

Utility Testing

Utilities are tested via:

• Unit Tests: Individual utility behavior
• Integration Tests: Utility interactions
• Performance Tests: Execution time benchmarks