archive-org-link-grabber/AGENTS.md

# 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).
 - Popup → Background (badge): `popup.filteredCount` posts the current filtered count so the background can set a per‑tab badge.

### Badges (Per‑tab)

- Background maintains lightweight per‑tab state `{ url, isArchive, itemsCount, filteredCount }`.
- Default: on archive.org `/download/*` tabs, badge shows total item count; on other tabs, it is blank.
- When the popup filters change, it sends `popup.filteredCount`, and the badge shows that filtered count for the active tab.
- Badge updates on tab activation and URL changes; quick actions (copy/send) update only the current tab’s badge.

### 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>/`), `release:push` (uploads artifacts and auto‑updates/uploads `releases/updates.json`).
- 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.