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.