Developer Getting Started

🛠️ Development Setup

Command Line Options

• --reset-settings or --wipe-settings: Reset all settings to defaults (useful for testing)

  Usage:

  # In development
  npm run build:electron && electron . --reset-settings
  
  # Or after building
  electron . --reset-settings

  This will delete the settings file at ~/.torrify/settings.json and restart with default settings.

Run the application in development mode:

npm run electron:dev

This will:

• Start the Vite dev server on http://localhost:5173
• Launch Electron with the application
• Enable hot module replacement
• Open DevTools automatically

Run only the Vite dev server (for browser testing):

npm run dev

🏗️ Building

Build the application for production:

# Build the application
npm run build

# Package into distributable (creates installer/executable)
npm run package

# Or build for specific platform (must be on that OS)
npm run package:win    # Windows NSIS installer (Windows only)
npm run package:mac    # macOS DMG (macOS only)
npm run package:linux  # Linux AppImage (Linux only)

Platform-Specific Build Requirements

Windows:

• Requires Developer Mode enabled (Settings → Privacy & Security → For developers)
• Or run PowerShell as Administrator
• Reason: electron-builder needs to create symbolic links

macOS:

• Must build on macOS (cannot cross-compile)
• Uses native Apple tools

Linux:

• Must build on Linux (or WSL on Windows)
• Cannot build AppImages on Windows/macOS directly
• Uses Linux-specific tools (mksquashfs)

Cross-Platform Building

To build for all platforms without having access to each OS:

• Use GitHub Actions CI/CD (see .github/workflows/build-installers.yml)
• Push to main branch triggers automatic builds for Windows, macOS, and Linux
• Download artifacts from GitHub Actions or Releases

Build Output

The built files will be in:

• dist/ - Renderer process (React app)
• dist-electron/ - Main process and preload script
• dist-installer/ - Packaged installers

For detailed build instructions, see DEV_README.md.

🧪 Testing

The project uses Vitest and React Testing Library for unit and integration tests across the renderer (components, hooks, services) and electron (validation, CAD services). CI runs the full suite with coverage and uploads to Codecov.

Running Tests

# Run all tests once
npm test

# Run tests in watch mode (recommended for development)
npm run test:watch

# Generate coverage report (terminal summary + coverage/ HTML)
npm run test:coverage

Test Structure

Tests live under electron/__tests__/, src/**/__tests__/, and root src/App.test.tsx. Key areas:

• electron: pathValidator, projectValidation, validation schemas, OpenSCADService, Build123dService, cadFactory
• src/components: ChatPanel, EditorPanel, PreviewPanel, SettingsModal, StlViewer, WelcomeModal, HelpBot, DemoDialog, ErrorBoundary, ConfirmDialog, FileToolbar, ProjectToolbar
• src/components/settings: GeneralSettings, AISettings, KnowledgeSettings
• src/hooks: useFileOperations, useRecentFiles, useDemo, useMenuHandlers
• src/services/cad: cad adapter, backend-connectivity
• src/services/llm: GatewayService, GeminiService, OpenRouterService, OllamaService, utils, prompts, index, code-generation

For the full tree and coverage details, see TESTING.md.

What's Tested

• ✅ Component rendering and user interactions (clicks, input)
• ✅ Hooks (file operations, recent files, demo, menu handlers)
• ✅ Settings panels (General, AI, Knowledge Base)
• ✅ LLM services (mocked providers; prompt/build coverage)
• ✅ Code-generation regression suite
• ✅ Electron validation (paths, project save/load, schemas) and CAD services (mocked spawn/fs)
• ✅ Error handling (ErrorBoundary, preview panel)