dev-sidecar (Agent Skills)
GitHubAgent skills, system prompts, and AI developer rules for docmirror/dev-sidecar
CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Commands
### Dependency Management
- Always use `pnpm install` (not `npm install`) from the repository root. The project uses pnpm workspaces with `shamefully-hoist=true`.
- If `pnpm install` reports conflicts, update the relevant `package.json` entries to compatible versions and re-run.
### Linting
- `pnpm lint` โ lint the entire repo (ESLint flat config via `@antfu/eslint-config`)
- `pnpm lint:fix` โ auto-fix lint issues
### Testing
- `pnpm --filter @docmirror/dev-sidecar test` โ run core package tests (Mocha + Chai)
- `pnpm --filter @docmirror/mitmproxy test` โ run proxy package tests
- Run a single test file:
- `pnpm --filter @docmirror/dev-sidecar test -- test/regex.test.js`
- `pnpm --filter @docmirror/mitmproxy test -- test/proxyTest.js`
### GUI Development (from `packages/gui/`)
- `npm run electron` โ launch the Electron app in dev mode (starts Vue dev server + Electron)
- `npm run serve` โ run only the Vue dev server (port 8080)
- `npm run electron:build` โ production build (Vue build + electron-builder)
- `npm run lint` โ lint GUI code only
- For debugging: run `npm run electron` and open DevTools (`F12` or View โ Toggle Developer Tools)
### Python Environment (needed for native module builds)
```shell
uv init .
uv sync
.venv/Scripts/activate # Windows; use `source .venv/bin/activate` on Linux/macOS
```
## Committing Changes
When work is finished and ready to commit, the AI assistant stages files, but the **human runs the commit command manually** โ every contributor signs their own commits with their personal GPG/SSH key, which the assistant cannot access.
1. **Review first**: run `git status`, `git diff`, and `git log --oneline -10` (to match the repo's message style). Stage only intended files; never stage secrets, build artifacts, or unrelated changes.
2. **Stage properly**: use `git add <files>` for new/modified files and `git rm <files>` for deletions (or `git add -u` to record filesystem deletions). Verify the staged set with `git status` before proceeding.
3. **Do NOT run `git commit` yourself.** Instead, print the **full `git commit` command** and let the user execute it manually, e.g.:
```
git commit -m "fix(cli): ไฟฎๅค xxx"
```
4. **Commit message style**: follow the repo's convention โ a `type(scope): subject` prefix (`fix(scope):`, `feat(scope):`, `chore:`, ...) with a Chinese summary; include a body of bullet points for non-trivial changes. Do not add signing flags (`--no-gpg-sign`, `--no-verify`) or commit/push on the user's behalf unless explicitly requested.
5. **Push only when explicitly asked**, and only after the user has committed.
## Architecture
This is a **pnpm workspace monorepo** (`[email protected]`) for a developer-sidecar proxy tool that accelerates access to GitHub, npm, Docker Hub, and other foreign sites for Chinese developers. It works by running a local MITM HTTPS proxy, injecting a root CA certificate, and applying DNS optimization, SNI rewriting, and request interception/redirection rules.
### Package dependency graph
```
gui โโdepends-onโโ> core โโforks-as-child-processโโ> mitmproxy
^ ^
cli โโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### Packages
**`packages/core`** (`@docmirror/dev-sidecar`) โ The orchestrator.
- Entry: `src/index.js` โ `src/expose.js`. Exports `startup()`, `shutdown()`, plus `config`, `event`, `shell`, `server`, `proxy`, `plugin`, `status`.
- Startup sequence: merge config โ fork mitmproxy child process โ set OS-level system proxy โ start plugins (git, node, pip, overwall).
- Config merges 4 layers: defaults (`src/config/index.js`, ~470 lines) โ remote shared โ remote personal โ user overrides (`~/.dev-sidecar/config.json`).
- Shell helpers (`src/shell/`) abstract OS commands: setting system proxy, installing CA certs, enabling loopback, killing processes by port.
- Plugins (`src/modules/plugin/`) follow a uniform `{ key, config, status, plugin: Factory(context) }` pattern.
**`packages/mitmproxy`** (`@docmirror/mitmproxy`) โ The proxy engine (runs as a child process).
- Entry: `src/index.js`. Creates HTTP and HTTPS proxy servers on consecutive ports (default: 31180 HTTP, 31181 HTTPS).
- Interceptor pipeline (`src/lib/interceptor/`): priority-ordered interceptors match domains+paths and apply actions (redirect, proxy, abort, cache, SNI rewrite, OPTIONS preflight, response replace, script injection).
- TLS/cert handling (`src/lib/proxy/tls/`): generates a local CA root cert (`~/.dev-sidecar/dev-sidecar.ca.crt`), then creates per-domain fake certs signed by it using `node-forge`. Fake servers are LRU-cached.
- DNS system (`src/lib/dns/`): multi-provider DNS resolution (UDP, TCP, DoH, DoT, preset IPs). Supports SNI-specific DNS lookup.
- Speed test (`src/lib/speed/`): measures latency/availability to domains, used for IP selection.
- `RequestCounter` (`src/lib/choice/`): dynamic backup failover โ tracks success/failure per backend, switches after 3 consecutive errors or <40% success rate.
**`packages/gui`** (`@docmirror/dev-sidecar-gui`) โ Electron + Vue 3 desktop app.
- Main process: `src/background.js` โ creates BrowserWindow, system tray, IPC bridges, single-instance lock, Windows shutdown hook.
- Renderer: Vue 3 with Vue Router (hash mode), Ant Design Vue 4, dark theme support.
- IPC bridge (`src/bridge/`): dynamic RPC โ main process exposes a flat API list, renderer calls methods via `ipcRenderer.invoke('apiInvoke', [path, args])`. Core events (status, error, speed) flow mainโrenderer via `webContents.send`.
- Pages: dashboard (index), accelerator server, system proxy, settings, help, plus per-plugin pages (free-eye, git, node, overwall, pip).
**`packages/cli`** (`@docmirror/dev-sidecar-cli`) โ Headless CLI launcher. Reads user config, calls `DevSidecar.api.startup()`.
**`packages/aur/`** โ Arch Linux PKGBUILD (not a JS package). **`packages/cli2/`** โ abandoned placeholder, ignore it.
### Key conventions
- **Module systems**: `core`, `mitmproxy`, and `cli` use implicit CommonJS (`.js` files, no `"type": "module"`). `gui` uses ESM (`"type": "module"`). The root `package.json` declares `"type": "module"` but this only affects root-level scripts.
- **Shared JSON5 parser**: `@docmirror/mitmproxy/src/json` is used across all packages for JSON5 config parsing.
- **Logging**: log4js-based; log files at `~/.dev-sidecar/logs/core.log`, `gui.log`, `server.log`. Logger factory at `packages/core/src/utils/util.logger.js`. Every category writes to file and, by default, also to stdout (`std` appender); set `DEV_SIDECAR_LOG_TO_CONSOLE=false` to keep logs file-only (CLI daemon sets this automatically).
- **Status/event bus**: `core/src/event.js` (EventEmitter) and `core/src/status.js` (central status tree updated via events).
- **CA certificate**: stored at `~/.dev-sidecar/dev-sidecar.ca.crt` and `~/.dev-sidecar/dev-sidecar.ca.key.pem`. Generated locally on first run.
- **Config on disk**: user overrides saved as diffs in `~/.dev-sidecar/config.json`. Merged runtime config written as `running.json` for the child process.
### Build environment requirements
- Node.js 22.x
- Python 3.11 with setuptools (or use `uv` with the project's `.python-version` and `pyproject.toml`)
- VS 2022 with C++ desktop development workload (Windows)
- Native modules need C++17: the `.npmrc` sets `CXXFLAGS="-std=c++17"`
### Vue config gotcha
`packages/gui/vue.config.cjs` sets `concatenateModules: false` in webpack production builds. This is **intentional** โ module concatenation breaks ant-design-vue's Symbol-based `provide/inject`, causing menu crashes, dark mode failures, and Select/Dropdown malfunctions.