Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ app-update.yml
yarn-error.log
/test
.vscode/settings.json
src/main/lang/index.ts
/data
package-lock.json
src/helper-go/rsrc_windows_amd64.syso
src/helper-go/rsrc_windows_386.syso
src/helper-go/go.sum
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Check .gitignore at line 35 and surrounding context
head -n 40 .gitignore | tail -n 10

Repository: TanNhatCMS/FlyEnv

Length of output: 244


🏁 Script executed:

# Look for go.sum and go.mod files in src/helper-go/
fd -t f '^go\.(sum|mod)$' src/helper-go/

Repository: TanNhatCMS/FlyEnv

Length of output: 81


🏁 Script executed:

# Check if there are any other go.sum files in the repository
fd -t f '^go\.sum$'

Repository: TanNhatCMS/FlyEnv

Length of output: 43


Remove src/helper-go/go.sum from .gitignore

In Go projects, go.sum contains cryptographic checksums of module versions and must be committed to version control to ensure reproducible builds and verify module integrity. The current .gitignore entry ignores it, which violates Go best practices and creates security and reproducibility risks.

Proposed fix
 src/helper-go/rsrc_windows_amd64.syso
 src/helper-go/rsrc_windows_386.syso
-src/helper-go/go.sum
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
src/helper-go/go.sum
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.gitignore at line 35, Remove the ignore entry for src/helper-go/go.sum from
.gitignore and ensure the module's go.sum is tracked and committed: delete the
line containing src/helper-go/go.sum in the .gitignore, add the helper-go
module's go.sum to version control (git add) and commit it so the checksum file
is present for reproducible builds and module integrity checks.

322 changes: 322 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,322 @@
# FlyEnv - AI Agent Development Guide

## Project Overview

**FlyEnv** is an All-In-One Full-Stack Environment Management Tool built with Electron and Vue 3. It provides a lightweight, modular development environment manager for Windows, macOS, and Linux, allowing developers to install and manage Apache, PHP, Node.js, Python, databases, and more—running natively without Docker.

- **Version**: 4.13.2
- **Electron Version**: 35.7.5
- **License**: MIT
- **Author**: Pengfei Xu
- **Repository**: https://github.com/xpf0000/FlyEnv

## Technology Stack

### Core Technologies
- **Frontend Framework**: Vue 3 (Composition API)
- **Desktop Framework**: Electron 35.7.5
- **Build Tool**: Vite 6.x + esbuild 0.25.x
- **Language**: TypeScript 5.8.x
- **State Management**: Pinia 3.x
- **UI Component Library**: Element Plus 2.11.x
- **Styling**: Tailwind CSS 3.4.x + SCSS
- **Internationalization**: Vue I18n 11.x

### Additional Libraries
- **Code Editor**: Monaco Editor
- **Terminal**: node-pty + xterm.js
- **HTTP Client**: Axios
- **Process Management**: child_process, node-pty
- **File Operations**: fs-extra
- **Markdown Processing**: markdown-it + Shiki

## Project Architecture

FlyEnv follows Electron's multi-process architecture with three main components:

### 1. Main Process (`/src/main`)
Acts as a command relay station between the renderer and fork processes.

**Key Files**:
- `index.ts` - Entry point, initializes Launcher
- `Launcher.ts` - Application bootstrap, single-instance lock, event handling
- `Application.ts` - Main application controller, window management, IPC handling

**Core Managers**:
- `WindowManager` - Browser window creation and management
- `TrayManager` - System tray functionality
- `MenuManager` - Application menus
- `ConfigManager` - Configuration persistence
- `ForkManager` - Forked process management
- `NodePTY` - Terminal PTY handling

### 2. Forked Asynchronous Process (`/src/fork`)
Executes all heavy commands asynchronously to prevent main thread blocking.

**Key Files**:
- `index.ts` - Fork process entry point
- `BaseManager.ts` - Command dispatcher
- `module/Base/index.ts` - Base class for all service modules

**Module Structure** (`/src/fork/module/`):
Each service has its own module (e.g., `Nginx/`, `Php/`, `Mysql/`). A typical module extends the `Base` class and implements:
- `_startServer(version)` - Start the service
- `_stopService(version)` - Stop the service
- `fetchAllOnlineVersion()` - Fetch available versions
- `installSoft()` - Download and install

### 3. Renderer Process (`/src/render`)
Vue 3-based UI application.

**Key Files**:
- `main.ts` - Renderer entry point
- `App.vue` - Root component
- `core/type.ts` - Module type definitions

**Directory Structure**:
- `components/` - Vue components organized by module
- `store/` - Pinia stores
- `util/` - Utility functions
- `style/` - Global styles (SCSS)

~~### 4. Helper Process (`/src/helper`)
Background helper process for privileged operations.~~

Deprecated. Only the Go version is used.

### 5. Go Helper (`/src/helper-go/`)
Go-based helper binary for platform-specific operations (Windows admin tasks).

### 6. Shared Code (`/src/shared`)
Shared utilities between all processes:
- `ForkPromise.ts` - Promise with progress callbacks
- `Process.ts` - Process management utilities
- `child-process.ts` - Child process helpers
- `utils.ts` - Platform detection utilities

### 7. Internationalization (`/src/lang`)
Supports 25+ languages with JSON-based translation files.

**Supported Languages**:
Arabic, Azerbaijani, Bengali, Czech, Danish, German, Greek, English, Spanish, Finnish, French, Indonesian, Italian, Japanese, Dutch, Norwegian, Polish, Portuguese, Portuguese (Brazil), Romanian, Russian, Swedish, Turkish, Ukrainian, Vietnamese, Chinese.

## Build System

### Build Scripts (package.json)

```bash
# Development
yarn dev # Start development server with hot reload
yarn clean:dev # Clean dist folder
yarn build-dev-runner # Build dev runner script

# Production Build
yarn build # Build for production (platform-specific)
yarn clean # Clean node-pty build
yarn postinstall # Install Electron app dependencies
```

### Build Process Flow

1. **Development** (`yarn dev`):
- Cleans dist folder
- Builds dev-runner.ts → `electron/dev-runner.mjs`
- Starts Vite dev server
- Watches main/ and fork/ directories for changes
- Restarts Electron on file changes

2. **Production** (`yarn build`):
- Cleans dist folder and node-pty build
- Builds main process with esbuild
- Builds fork process with esbuild
- Builds renderer with Vite
- Packages with electron-builder

### esbuild Configuration (`/configs/esbuild.config.ts`)

| Target | Entry | Output | Minify |
|--------|-------|--------|--------|
| dev | src/main/index.dev.ts | dist/electron/main.mjs | false |
| dist | src/main/index.ts | dist/electron/main.mjs | true |
| devFork | src/fork/index.ts | dist/electron/fork.mjs | false |
| distFork | src/fork/index.ts | dist/electron/fork.mjs | true |
| devHelper | src/helper/index.ts | dist/helper/helper.js | true |
| distHelper | src/helper/index.ts | dist/helper/helper.js | true |

### Vite Configuration (`/configs/vite.config.ts`)

**Entry Points**:
- `main` - Main application window
- `tray` - Tray popup window
- `capturer` - Screen capture window

**Path Aliases**:
- `@` → `src/render/`
- `@shared` → `src/shared/`
- `@lang` → `src/lang/`

## Code Style Guidelines

### ESLint Configuration
- Uses flat config format (`eslint.config.mjs`)
- TypeScript ESLint recommended rules
- Vue 3 recommended rules
- Prettier integration for formatting

### Key Rules
- `@typescript-eslint/no-explicit-any`: error (disabled in practice)
- `vue/multi-word-component-names`: off
- `vue/block-lang`: requires TypeScript in Vue SFCs
- `prettier/prettier`: error (formatting issues treated as errors)

### Styling
- **Primary**: Tailwind CSS for utility-first styling
- **Secondary**: SCSS for complex styles
- **Dark Mode**: CSS selector-based (`darkMode: 'selector'`)

### Code Conventions
- Use TypeScript for all new code
- Vue SFCs must use `<script lang="ts">`
- Prefer Composition API over Options API
- Use Pinia for state management
- Follow existing module patterns for new services

## Adding a New Module

### Step 1: Define Module Type
Add to `src/render/core/type.ts` in `AppModuleEnum`:

```typescript
export enum AppModuleEnum {
myservice = 'myservice',
// ... existing modules
}
```

### Step 2: Create Fork Module
Create `/src/fork/module/MyService/index.ts`:

```typescript
import { Base } from '../Base';
import type { SoftInstalled } from '@shared/app';

class MyService extends Base {
constructor() {
super();
this.type = 'myservice';
}

async _startServer(version: SoftInstalled) {
// Implementation
}

async _stopService(version: SoftInstalled) {
// Implementation
}
}

export default new MyService();
```

### Step 3: Create Renderer Components
Create `/src/render/components/MyService/`:
- `Module.ts` - Module definition
- `Index.vue` - Main view
- `aside.vue` - Sidebar component

### Step 4: Add Translations
Create translation files in `/src/lang/*/myservice.json` and add to `index.ts`.

## Testing

### Test Directory (`/test/`)
Contains various test files and utilities:
- `test.ts` - General test file
- `powershell.ts` - PowerShell tests
- `docker-compose.yml` - Docker test configuration

**Note**: The project currently does not have automated unit tests configured. Testing is primarily done manually during development.

## Development Workflow

### Prerequisites
- Node.js 18+
- Yarn package manager
- Platform-specific build tools:
- **macOS**: Xcode Command Line Tools
- **Windows**: Visual Studio Build Tools
- **Linux**: build-essential

### Getting Started

```bash
# Clone and install
git clone git@github.com:xpf0000/FlyEnv.git
cd FlyEnv
yarn install

# Development
yarn dev

# Build for production
yarn build
```

### Platform-Specific Notes

**macOS**:
- May require `sudo xattr -dr "com.apple.quarantine"` for helper binaries
- Uses `flyenv-helper` for privileged operations

**Windows**:
- Uses `flyenv-helper-windows-amd64-v1.exe` Go binary for admin tasks
- PowerShell scripts in `/scripts/`

**Linux**:
- Supports both .deb and .rpm packaging
- Uses native package managers for dependencies

## Security Considerations

1. **Privilege Escalation**: Uses helper processes for root/admin operations
2. **Code Signing**: Configured for macOS notarization and signing
3. **Sandbox**: Disables GPU sandbox for certain operations
4. **Process Isolation**: Forked process for command execution

## Deployment

### GitHub Actions Workflows
- `.github/workflows/macos-version-build.yml`
- `.github/workflows/windows-version-build.yml`
- `.github/workflows/linux-version-build.yml`

### Release Artifacts
- **macOS**: `.dmg` (Intel & Apple Silicon)
- **Windows**: `.exe` installer and portable
- **Linux**: `.deb` and `.rpm` packages

## Useful Commands

```bash
# Fix macOS helper permissions
yarn fix-flyenv-helper

# Kill running Electron processes (Windows)
npx tsx scripts/electron-process-kill.ts

# Update dependencies
yarn upgrade-interactive
```

## Common Issues

1. **node-pty build failures**: Run `yarn clean` and rebuild
2. **Port conflicts**: Default dev port is defined in `configs/vite.port.ts`
3. **Module not found**: Ensure all path aliases are correctly resolved

## Resources

- **Website**: https://www.flyenv.com
- **Documentation**: https://deepwiki.com/xpf0000/FlyEnv
- **Discord**: https://discord.gg/u5SuMGxjPE
- **Releases**: https://github.com/xpf0000/FlyEnv/releases
Loading