archive-org-link-grabber/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Root: manifest.json, package.json (when added), config files.
• src/: extension code.
  • background/: RPC, messaging, and long‑lived tasks.
  • content/: archive.org DOM parsing on /download/* pages.
  • popup/ and options/: UI, settings, and actions.
  • lib/: shared utils (filters, size/date parsing, aria2 client).
• assets/: icons and static resources.
• tests/: unit (tests/unit) and e2e (tests/e2e).
• Note: initial repo is docs-first; scaffolding will create these paths.

Build, Test, and Development Commands

• Install: npm install (after package.json lands).
• Dev (Firefox): npx web-ext run --source-dir . or npm run dev.
• Build: npx web-ext build -o -a dist or npm run build → dist/.
• Lint/Format: npm run lint and npm run format.
• Tests: npm test (Jest). E2E via Playwright: npm run test:e2e.

Coding Style & Naming Conventions

• Language: JavaScript (ES2020+) or TypeScript (preferred for new modules).
• Indentation: 2 spaces; max line length 100; use semicolons.
• Filenames: kebab-case (filters-utils.ts, aria2-client.ts). UI components: PascalCase.
• Identifiers: camelCase; UPPER_SNAKE_CASE for constants; verbs for functions.
• Tools: ESLint + Prettier. Run npm run lint before pushing.

Testing Guidelines

• Framework: Jest for unit tests; Playwright for e2e (popup/content behaviors).
• Location: unit under tests/unit/**/*.spec.(js|ts); e2e under tests/e2e/**.
• Coverage: target ≥ 80% lines for core filters and RPC client.
• Focus: filename/type regex, size/date filters, clipboard, and aria2.addUri payloads.

Commit & Pull Request Guidelines

• Commits: Conventional Commits (feat:, fix:, docs:, chore:, refactor:). Use imperative mood.
• PRs: concise description, motivation, screenshots/GIFs for UI, test plan, and linked issues.
• Scope: keep PRs small and focused; update docs when behavior changes.

Security & Configuration Tips

• Do not commit secrets. Store aria2 RPC token in browser.storage.local.
• Prefer HTTPS for remote RPC; if self-signed, document trust steps locally only.
• Provide examples as config.example.json; ignore local overrides in .gitignore.