63 lines
3.5 KiB
Markdown
63 lines
3.5 KiB
Markdown
# Project instructions
|
|
|
|
## Scope
|
|
|
|
This repository contains the Firefox WebExtension **Proxy Switcher Fork By WT**. It uses Manifest V2, a persistent background script, plain HTML/CSS/JavaScript, and no runtime dependencies.
|
|
|
|
## Source layout
|
|
|
|
- `manifest.json` — Firefox Manifest V2 metadata, permissions, icons, popup, options page, and Firefox/Android compatibility.
|
|
- `manifest.chrome.json` — Chrome/Chromium Manifest V3 metadata.
|
|
- `background.js` — proxy routing, proxy authentication, tab-domain tracking, and runtime message handling.
|
|
- `background-chrome.js` and `background-service-worker.js` — Chrome/Chromium PAC routing and Manifest V3 service worker.
|
|
- `browser-api.js` — Promise-based API adapter used by shared popup/options pages on Chromium.
|
|
- `config-manager.js` — local configuration storage and update API.
|
|
- `popup.html`, `popup.js`, `popup.css` — current-domain quick controls.
|
|
- `options.html`, `options.js`, `options.css` — profiles, domains, management actions, and Advanced Settings.
|
|
- `icons/` — extension icon sizes referenced by `manifest.json`.
|
|
- `Makefile` — build and cleanup commands.
|
|
- `.github/workflows/release.yml` — per-push package builds, workflow artifacts, and release-triggered AMO/Chrome Web Store publishing.
|
|
|
|
## Development rules
|
|
|
|
- Keep all configuration local. Do not add telemetry, remote requests, analytics, or external script dependencies.
|
|
- Preserve the `browser.*` WebExtension API style in shared UI code. Firefox uses Manifest V2 and `proxy.onRequest`; Chromium uses Manifest V3, `chrome.proxy.settings`, and a PAC script.
|
|
- Keep the Firefox Android minimum version at 113 or newer when using the `gecko_android` manifest key.
|
|
- Keep the Firefox and Chromium manifests as separate build targets. Do not replace the Firefox proxy listener with the Chrome PAC implementation.
|
|
- Proxy settings are domain-specific. A missing domain entry means direct connection; an entry with `enabled: false` is configured but disabled.
|
|
- Keep popup and options theme behavior consistent. Supported theme values are `system`, `light`, and `dark`.
|
|
- When changing an icon, update every size referenced by the manifest and verify the XPI contains the new paths.
|
|
- Never hand-edit or retain stale `META-INF` signatures after changing files. Build artifacts must be signed again before distribution.
|
|
- Do not commit generated `web-ext-artifacts/` packages unless explicitly requested.
|
|
- Keep publishing credentials only in GitHub Secrets. The release workflow expects AMO JWT credentials and Chrome Web Store OAuth credentials.
|
|
- Keep `amo-metadata.json` valid for AMO listed submissions; keep `version.license` consistent with the MIT `LICENSE` file.
|
|
- Missing or incomplete store credentials must skip only that store's deployment. Keep package builds, release assets, and workflow artifacts available without store credentials.
|
|
|
|
## Validation
|
|
|
|
Run these checks after source changes:
|
|
|
|
```sh
|
|
node --check background.js
|
|
node --check config-manager.js
|
|
node --check popup.js
|
|
node --check options.js
|
|
python -m json.tool manifest.json >/dev/null
|
|
```
|
|
|
|
Build a package with:
|
|
|
|
```sh
|
|
make build
|
|
```
|
|
|
|
The resulting XPI is written to `web-ext-artifacts/`. It is unsigned when produced by `web-ext build`; Android installation requires a package signed by Mozilla/AMO.
|
|
|
|
Build the Chrome/Chromium package with:
|
|
|
|
```sh
|
|
make build-chrome
|
|
```
|
|
|
|
The resulting ZIP is written to `web-ext-artifacts/proxyswitcherforkbywt-chrome.zip`. Chrome Android and iOS do not support ordinary extension installation.
|