89 lines
5.1 KiB
Markdown
89 lines
5.1 KiB
Markdown
# Contributor Guide & Philosophy
|
||
|
||
This add-on helps you collect and filter links from archive.org `https://archive.org/download/*` pages, then copy them or send them to an aria2 RPC server. The project is Firefox-first, docs-first, and aims to stay lean and privacy‑respecting.
|
||
|
||
## Architecture Overview
|
||
|
||
- Manifest: Firefox Manifest V2 (for stability and background script support).
|
||
- Background (MV2, non-module): `src/background/index.js` handles messaging, context menu, on-demand content script injection, and delegates aria2 calls to globals from `src/lib/aria2-bg.js`.
|
||
- Content script: `src/content/collect.js` scrapes the download listing DOM and returns items `{ url, name, type, sizeText?, dateText? }`.
|
||
- Popup UI: `src/popup/*` lets users filter by name/type (string or regex), size, and date, preview matches, copy links, or send to aria2.
|
||
- Options page: `src/options/*` manages aria2 endpoint/secret, “Default Action” (download vs copy), and an “Include metadata in All” toggle; includes a connection test for aria2 with HTTPS‑Only hints.
|
||
- Shared utils: `src/lib/filters.js` (matchers, size/date parsing) and `src/lib/aria2.js` (JSON‑RPC helpers). `src/lib/aria2-bg.js` exposes background‑safe helpers on `globalThis`.
|
||
|
||
### Messaging and Flow
|
||
|
||
- Popup → Content: try `collectLinks` first; if no receiver exists, Popup → Background → inject content → retry collect.
|
||
- Popup → Background: `aria2.send` wraps `aria2.addUri` calls (batch) and keeps secrets out of page context.
|
||
- Context menu: parent "Collect links…" with a dynamic submenu built per page ("Download/Copy All" and top file types).
|
||
|
||
### Storage Keys
|
||
|
||
- `aria2`: `{ endpoint, secret }` in `browser.storage.local`.
|
||
- `prefs`: `{ defaultAction: 'download'|'copy', allIncludeMeta: boolean }`.
|
||
- `lastCollected`/`lastItems`: background stores the last collection stats and items to support quick actions and badges.
|
||
|
||
## Design Principles
|
||
|
||
- Firefox-first: target Firefox with MV2; revisit MV3 later if appropriate.
|
||
- Minimal footprint: no heavy frameworks; keep UI simple and dependency‑light.
|
||
- Privacy by default: no analytics; tokens stored in `storage.local`; users own their data.
|
||
- Robust UX: inject content on demand; show actionable error messages (e.g., HTTPS‑Only hints).
|
||
- Clear boundaries: background mediates network and privileged actions; content stays read‑only.
|
||
- Docs-first: keep README and this guide authoritative; code mirrors described behaviors.
|
||
|
||
## Repository Layout (current)
|
||
|
||
- Root: `manifest.json`, `package.json`, `LICENSE`, `README.md`, `.env.example`, `releases/`, `scripts/`.
|
||
- `src/`
|
||
- `background/index.js`
|
||
- `content/collect.js`
|
||
- `popup/` (`index.html`, `index.js`, `styles.css`)
|
||
- `options/` (`index.html`, `index.js`, `styles.css`)
|
||
- `lib/` (`filters.js`, `aria2.js`, `aria2-bg.js`)
|
||
|
||
Note: There is no `tests/` directory yet. See “Testing” below for priorities.
|
||
|
||
## Development
|
||
|
||
- Install: `npm install`
|
||
- Dev (Firefox): `npm run dev` (starts Firefox with `web-ext run`)
|
||
- Build: `npm run build` → artifacts in `dist/`
|
||
- Lint (AMO): `npm run lint:fx`
|
||
- Local release: see “Release & Signing”
|
||
|
||
## Coding Style
|
||
|
||
- Language: JavaScript (ES2020+). TypeScript may be introduced later; keep modules TS‑friendly.
|
||
- Conventions: 2 spaces; max line length ~100; semicolons; kebab-case filenames; camelCase identifiers; UPPER_SNAKE_CASE for constants; verbs for functions.
|
||
- Dependencies: keep minimal; prefer DOM APIs and small modules in `src/lib`.
|
||
- Structure: small functions, early returns for clarity; avoid incidental coupling between popup/background/content.
|
||
|
||
## Testing
|
||
|
||
Tests are not yet implemented. Priorities when adding tests:
|
||
|
||
- Unit (Jest): `src/lib/filters.js` (matchers, size/date parsing) and `src/lib/aria2.js` (payloads, token handling).
|
||
- Integration (web‑ext + Playwright): popup filtering behavior on a fixture page; content collector DOM parsing; context menu quick actions update and badge counts.
|
||
- Coverage targets: ≥80% for filters and aria2 client.
|
||
|
||
Suggested scripts (future): `npm test`, `npm run test:e2e` with Playwright.
|
||
|
||
## Security & Permissions
|
||
|
||
- Do not commit secrets; use `.env` only for local signing. The aria2 secret is stored in `browser.storage.local`.
|
||
- Prefer HTTPS for remote aria2 RPC. For self‑signed certs, document local trust steps only.
|
||
- Manifest host permissions include `archive.org` and wildcard entries to allow non‑local RPC endpoints. If repackaging, scope these down to intended hosts.
|
||
- Firefox HTTPS‑Only Mode can upgrade `http://` to `https://` for non‑local hosts; the options page surfaces guidance.
|
||
|
||
## Release & Signing
|
||
|
||
- Add‑on ID and updates: `applications.gecko.id = "archive-org-link-grabber@jordanwages.com"` and `applications.gecko.update_url` points to the self‑hosted updates JSON.
|
||
- Scripts: `release:prepare:*` (syncs `manifest.json`), `release:sign` (creates XPI under `releases/<version>/`).
|
||
- Secrets: set `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` locally (see `.env.example`); never commit them.
|
||
|
||
## Commit & PR Guidelines
|
||
|
||
- Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`.
|
||
- Keep PRs small and focused; include motivation, UX screenshots for UI changes, test plan, and linked issues.
|
||
|