Contributing to metacubexd

Thanks for helping improve metacubexd. Keep changes focused, explain the user impact, and include the checks you ran.

Security vulnerabilities must not be reported in a public issue, discussion, or pull request. Follow the security policy instead.

Prerequisites and setup

• Node.js 24 (see .node-version)
• Corepack with pnpm 10.34.1 (see the packageManager field in package.json)
• Platform tooling required by the package you are changing

corepack enable
pnpm install

This repository is a pnpm workspace with four main packages:

Package	Responsibility
packages/ui	Nuxt dashboard, static panel, and desktop renderer
packages/agent	Shared mihomo lifecycle and profile-management logic
apps/server	Nitro server and container runtime
apps/desktop	Electron main process, preload, native helpers, and packaging

Read CONTEXT.md for the system boundaries. UI work should also follow PRODUCT.md and DESIGN.md. Agent behavior and its HTTP contract are documented in MANUAL.md.

Develop and build

Run commands from the repository root unless noted otherwise.

Scope	Develop	Build
UI	pnpm dev	pnpm build:ui
Server	pnpm dev:server	pnpm build:server
Desktop	pnpm dev:desktop	pnpm build:desktop

pnpm build:server builds the Nitro server and its agent dependency; it does not build the UI. pnpm build builds the UI and server. pnpm build:desktop builds the Electron TypeScript bundles only; it does not create an installer. Official installers additionally require a generated desktop renderer, the correct mihomo binary and platform packaging tools. Use the release workflow as the source of truth for desktop packaging.

Tests and checks

Run the checks relevant to every package you changed. Before opening a pull request, also run the workspace-wide static checks when practical:

pnpm typecheck
pnpm lint

pnpm lint currently runs the UI linter with --fix; inspect its changes before staging them.

Package tests are intentionally explicit:

pnpm --filter @metacubexd/ui test:unit
pnpm --filter @metacubexd/ui test:e2e
pnpm --filter @metacubexd/agent test
pnpm --filter @metacubexd/server test
pnpm --filter @metacubexd/desktop test

UI end-to-end tests require Playwright's Chromium binary:

pnpm --filter @metacubexd/ui exec playwright install chromium

If a check is not applicable or cannot run on your platform, state that clearly in the pull request. Do not imply that unrun checks passed.

Documentation and translations

• Update the README and package documentation when behavior, configuration, architecture, or deployment changes.
• Keep the seven locale files in packages/ui/i18n/locales aligned when adding or changing user-facing text.
• Update screenshots when the visible UI materially changes.
• Never put tokens, subscription URLs, profile contents, private keys, or other credentials in fixtures, logs, screenshots, issues, or pull requests.

Markdown files can be checked with the repository's Prettier installation:

pnpm exec prettier --check README.md CONTRIBUTING.md .github/SECURITY.md

Commits and pull requests

Use focused Conventional Commits such as fix(desktop): quote Windows proxy paths or docs: clarify server authentication. Avoid committing generated build output. Only change pnpm-lock.yaml when dependencies or their resolution changed.

Every pull request should include:

• A concise description of the problem and solution.
• A linked issue when one exists.
• Tests and manual checks performed, including OS and architecture.
• Before-and-after screenshots or recordings for visible UI changes.
• Compatibility, migration, permission, and security implications.

Desktop smoke testing

Changes to Electron lifecycle, system proxy, TUN, native helpers, kernel management, or packaging need real-platform smoke testing. Test macOS, Windows, and Linux when the change can affect all three; otherwise list untested platforms in the pull request.

On each applicable platform, verify:

• The app installs or launches, starts its bundled kernel, and opens a working managed dashboard endpoint.
• A profile can be imported, edited, validated, activated, and used after the kernel restart.
• System proxy can be enabled and disabled, and quitting does not leave an unintended proxy configuration behind.
• TUN setup requests the expected privilege, can be disabled again, and reports helper or service failures clearly.
• Tray, window close, reopen, and quit behavior remain correct.
• Logs and diagnostics do not expose secrets.

Also cover platform-specific integration points:

Platform	Checks
macOS	Gatekeeper/quarantine behavior, helper installation, and Apple Silicon/Intel when applicable
Windows	SmartScreen/UAC, system-proxy registry writes, the TUN service, and x64/arm64 when applicable
Linux	AppImage, deb, rpm, or pacman package launch; pkexec/systemd integration; desktop proxy settings; /dev/net/tun; and x64/arm64 when applicable

Unsigned local packages are development artifacts. Do not present them as an official release or ask users to bypass platform security controls without a clear, scoped reason.