Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
67 changes: 67 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What is Proxyverse?

A Manifest V3 browser extension (Chrome, Edge, Firefox) for proxy profile management with auto-switch rules and PAC script support. It is an alternative to Proxy SwitchyOmega.

## Build and Test Commands

```bash
npm run build # Type-check (vue-tsc) + build for Chrome/Edge
npm run build:firefox # Type-check + build for Firefox (transforms manifest)
npm run build:test # Build in test mode (no Sentry, no visualizer)
npm run dev # Vite dev server
npm test # Run vitest in watch mode
npm run coverage # Single run with coverage report
npx vitest run tests/services/proxy/profile2config.test.ts # Run a single test file
```

CI runs `npm run coverage` on PRs to main/develop; `npm run build` + `npm run build:firefox` on pushes and tags.

## Architecture

### Three build entry points

The Vite config defines three entry points that produce the extension bundle:
- **`index.html`** / **`popup.html`** -- Both load `src/main.ts` (Vue app). The Vue router uses hash history: `#/popup` renders `PopupPage`, `#/` renders `ConfigPage` with nested profile/preference routes.
- **`src/background.ts`** -- Service worker. Wires up proxy auth, request stats, and badge indicator. No Vue, no DOM.

### Browser adapter layer (`src/adapters/`)

`BaseAdapter` defines the abstract contract for all browser APIs (storage, proxy, webRequest, tabs, i18n). Concrete implementations: `Chrome`, `Firefox`, `WebBrowser` (dev stub). A singleton `Host` is auto-detected at import time and used everywhere. This is the only layer that touches `chrome.*` or `browser.*` APIs directly.

### Proxy engine (`src/services/proxy/`)

The core complexity lives here:
- **`profile2config.ts`** -- `ProfileConverter` turns a `ProxyProfile` into a `ProxyConfig` (for `chrome.proxy.settings`). For non-PAC profiles and auto-switch profiles, it **generates PAC scripts via AST** using `escodegen`/`acorn` node builders in `scriptHelper.ts`. Auto-switch profiles compose multiple sub-profiles by generating `register()` calls that build a lookup table.
- **`pacSimulator.ts`** -- JS reimplementations of PAC functions (`shExpMatch`, `isInNet`) used to simulate PAC evaluation in-extension (e.g., for tab badge resolution). `isInNet` returns `UNKNOWN` when given a hostname instead of an IP (can't do DNS in extension context).
- **`auth.ts`** -- Resolves proxy auth credentials by walking the profile tree (auto-switch profiles delegate to sub-profiles).

### Profile system (`src/services/profile.ts`)

Profiles are stored in `chrome.storage.local` under key `"profiles"`. Types: `ProfileSimple` (proxy/pac), `ProfilePreset` (system/direct), `ProfileAutoSwitch` (rule-based routing). System profiles `DIRECT` and `SYSTEM` have fixed IDs `"direct"` and `"system"`.

### Config import/export (`src/services/config/schema/`)

Schema definitions for importing/exporting profile configurations using `io-ts` for runtime type validation.

## Critical Gotcha: `deepClone()` must use JSON round-trip

`deepClone()` in `src/services/utils.ts` uses `JSON.parse(JSON.stringify(obj))`. **Do not replace with `structuredClone()`** -- Vue's reactive Proxy objects throw `DataCloneError` under `structuredClone()`. The JSON round-trip serializes through Vue's Proxy traps and produces plain objects safe for `chrome.storage`.

## Firefox build differences

The `vite.config.ts` `TRANSFORMER_CONFIG` rewrites `manifest.json` at build time for Firefox:
- Replaces `background.service_worker` with `background.scripts` array
- Removes `version_name`
- Adds `browser_specific_settings.gecko`

## Path alias

`@/` maps to `src/` (configured in both `vite.config.ts` and `tsconfig.json`).

## i18n

Translation strings live in `public/_locales/{locale}/messages.json`. Translations are managed via Transifex.
2 changes: 1 addition & 1 deletion public/_locales/en/messages.json
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@
"message": "Bypass List"
},
"config_section_advance": {
"message": "Advance Config"
"message": "Advanced Config"
},
"config_reference_bypass_list": {
"message": "Learn more about bypass list"
Expand Down
22 changes: 12 additions & 10 deletions src/background.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ class ProxyAuthProvider {
static requests: Record<string, number> = {};

static onCompleted(
details: WebResponseDetails | WebRequestErrorOccurredDetails
details: WebResponseDetails | WebRequestErrorOccurredDetails,
) {
if (ProxyAuthProvider.requests[details.requestId]) {
delete ProxyAuthProvider.requests[details.requestId];
Expand All @@ -43,7 +43,7 @@ class ProxyAuthProvider {

static onAuthRequired(
details: WebAuthenticationChallengeDetails,
asyncCallback?: (response: BlockingResponse) => void
asyncCallback?: (response: BlockingResponse) => void,
): BlockingResponse | undefined {
if (!details.isProxy) {
asyncCallback && asyncCallback({});
Expand All @@ -60,10 +60,10 @@ class ProxyAuthProvider {
getAuthInfos(details.challenger.host, details.challenger.port).then(
(authInfos) => {
const auth = authInfos.at(
ProxyAuthProvider.requests[details.requestId]
ProxyAuthProvider.requests[details.requestId],
);
if (!auth) {
asyncCallback && asyncCallback({ cancel: true });
asyncCallback && asyncCallback({});
return;
}

Expand All @@ -75,7 +75,7 @@ class ProxyAuthProvider {
},
});
return;
}
},
);
}
}
Expand All @@ -96,12 +96,14 @@ class StatsProvider {
// this.stats.addFailedRequest(details);
// TODO: update indicator
const proxySetting = await getCurrentProxySetting();
console.log("onResponseStarted", details);
if (details.tabId > 0 && proxySetting.activeProfile) {
const ret = await findProfile(
proxySetting.activeProfile,
new URL(details.url)
);
let parsedUrl: URL;
try {
parsedUrl = new URL(details.url);
} catch {
return;
}
const ret = await findProfile(proxySetting.activeProfile, parsedUrl);

StatsProvider.stats.setCurrentProfile(details.tabId, ret);

Expand Down
1 change: 0 additions & 1 deletion src/components/configs/AutoSwitchInput.vue
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,6 @@ const getConditionInputRule = (type: AutoSwitchType): FieldRule<string> => {
case "url":
return {
validator: async (value: string, cb: (message?: string) => void) => {
console.log("test");
let u;
try {
u = new URL(value || "");
Expand Down
1 change: 0 additions & 1 deletion src/components/controls/ThemeSwitcher.vue
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ const onDarkModeChanged = (newMode: DarkMode) => {
};
const toggleDarkMode = async () => {
console.log(await currentDarkMode());
switch (await currentDarkMode()) {
case DarkMode.Dark:
onDarkModeChanged(DarkMode.Light);
Expand Down
4 changes: 1 addition & 3 deletions src/pages/PopupPage.vue
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,12 @@ onMounted(async () => {
const jumpTo = (to: RouteLocationRaw) => {
const path = router.resolve(to).fullPath;
window.open(`/index.html#${path}`, import.meta.url);
// window.open(router.resolve(to).href, import.meta.url)
window.open(`/index.html#${path}`, "_blank");
};
// actions
const setProxyByProfile = async (val: ProxyProfile) => {
try {
console.log(toRaw(val));
await setProxy(toRaw(val));
activeProfile.value = toRaw(val);
} catch (e: any) {
Expand Down
4 changes: 2 additions & 2 deletions src/services/preference.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,10 +53,10 @@ export async function changeDarkMode(newMode: DarkMode) {

switch (newMode) {
case DarkMode.Dark:
document && document.body.setAttribute("arco-theme", "dark");
document?.body?.setAttribute("arco-theme", "dark");
break;
case DarkMode.Light:
document && document.body.removeAttribute("arco-theme");
document?.body?.removeAttribute("arco-theme");
break;
}
}
2 changes: 1 addition & 1 deletion src/services/profile.ts
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ async function overwriteProfiles(profiles: ProfilesStorage) {
// Deep clone to remove any Proxy objects before saving
const clonedProfiles = deepClone(profiles);
await Host.set(keyProfileStorage, clonedProfiles);
onProfileUpdateListeners.map((cb) => cb(profiles));
onProfileUpdateListeners.forEach((cb) => cb(profiles));
}

/**
Expand Down
2 changes: 1 addition & 1 deletion src/services/proxy/auth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ export class ProfileAuthProvider {
];

// check if there's any matching host and port
auths.map((item) => {
auths.forEach((item) => {
if (!item) return;

if (
Expand Down
2 changes: 1 addition & 1 deletion src/services/proxy/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ export async function refreshProxy() {
const newProfile = await getProfile(current.activeProfile.profileID);

// if it's preset profiles, then do nothing
if (!newProfile || current.activeProfile.proxyType in ["system", "direct"]) {
if (!newProfile || ["system", "direct"].includes(current.activeProfile.proxyType)) {
return;
}

Expand Down
5 changes: 5 additions & 0 deletions src/services/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@
* Deep clone an object to remove all Proxy objects (e.g., from Vue reactivity).
* This is necessary because chrome.storage and browser.storage use structured clone
* which cannot clone Proxy objects.
*
* Note: structuredClone() is NOT used here intentionally — it throws a DataCloneError
* on JavaScript Proxy objects (including Vue reactive/ref wrappers). JSON round-trip
* serializes through the Proxy traps and produces a plain object, which is exactly
* what chrome.storage requires.
*/
export function deepClone<T>(obj: T): T {
return JSON.parse(JSON.stringify(obj));
Expand Down
Loading