search-with-chatgpt-powered-by-openai-extension/AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization

This is a Firefox WebExtension (Manifest V2) with npm-based development tooling.

- `manifest.json` defines the extension metadata, the ChatGPT search provider,
  the background script, the options panel, and the keyboard command.
- `lib/` holds pure logic with no browser dependencies: `defaults.js`,
  `build-url.js`, and `settings.js`. This is the unit-tested core.
- `background/background.js` is an ES-module background script that registers
  the context menu and the keyboard command.
- `options/` is the options panel rendered inline in `about:addons`.
- `test/` holds `node:test` unit tests. Excluded from the packaged ZIP.
- `icons/` contains size-specific PNG artwork named `powered-by-openai-icon-<size>x<size>.png`.
- `web-ext-config.mjs` controls linting, local execution, and ZIP packaging.
- `docs/superpowers/` holds specs and plans. Excluded from the packaged ZIP.
- `.gitea/workflows/firefox-extension.yml` validates pull requests and protected branches.
- `README.md`, `CHANGELOG.md`, and `LICENSE.txt` cover usage, releases, and licensing.

## Browser Scope

Firefox Desktop is the only current implementation and release target. Do not add Chrome, Brave, Chromium, or other browser packaging—or modify the sibling Chrome repository—unless a task explicitly requests it. Future ports remain desirable, so prefer standard WebExtension APIs where they preserve Firefox behavior and isolate unavoidable Firefox-specific code.

## Build, Test, and Development Commands

- `npm ci` installs the exact dependencies from `package-lock.json`; use Node.js 22 or newer.
- `npm run dev` launches a temporary Firefox profile with automatic extension reload.
- `npm run lint` runs strict Mozilla extension validation.
- `npm run test:unit` runs the `node:test` unit tests over `test/`.
- `npm run build` creates the unsigned ZIP under `web-ext-artifacts/`.
- `npm test` runs lint, unit tests, and build together; run it before every pull request.

## Coding Style & Naming Conventions

Use two-space indentation in JSON, YAML, and JavaScript configuration. Preserve logical key grouping in `manifest.json`. Use lowercase, hyphenated filenames and include dimensions in icon names. Keep changes focused and avoid adding runtime dependencies without a concrete need.

## Testing Guidelines

Unit tests cover the pure logic in `lib/` via `node:test`; automated checks
otherwise cover manifest validation and packaging, not browser behaviour. Note
`node --test` exits 0 when it discovers no test files, so confirm a non-zero
test count rather than trusting the exit code alone.

After `npm test`, use `npm run dev` and confirm:

- `gpt <query>` opens ChatGPT, the provider stays non-default, and Firefox
  search settings can configure it.
- The Options/Preferences tab renders all five settings plus Restore defaults,
  in both light and dark themes and at a narrow window width, and values
  persist across a restart.
- The right-click **Ask ChatGPT** item appears only when text is selected.
- `Alt+Shift+G` acts on the selection and opens a blank chat when nothing is
  selected or on a restricted page such as `about:config`. Press the key to test
  this — `commands.getAll()` reports a shortcut as registered even when Firefox
  has silently overridden it. The injected snippet is gated on
  `document.hasFocus()`, so cover all four frame cases:
  - Select in the top frame → the top-frame text arrives.
  - Select inside an iframe → the iframe text arrives.
  - Select in the top frame, *then* select inside an iframe → the iframe text
    arrives. `hasFocus()` is true for a focused frame and all its ancestors, so
    if the stale top-frame text arrives instead, exclude ancestors by also
    checking that `document.activeElement` is not the frame element.
  - Press `Ctrl+F`, find a term, then press the shortcut without clicking back
    into the page → a blank chat is expected. Firefox leaves focus in the
    findbar, so no content frame reports focus. This is a deliberate trade: a
    stale cross-origin frame silently seeding the prompt was the worse failure.

Inspect ZIP contents whenever packaging rules or assets change; `test/` and
`docs/` must never appear, not even as empty directory entries.

Gitea Actions runs checks for every pull request and pushes to `develop` and
`main`. Only successful `main` pushes upload an unsigned build artifact; CI does
not publish to AMO.

## Commit & Pull Request Guidelines

Recent history uses short, lowercase prefixes such as `doc:` and `build:` (for example, `doc: fix git url`). Follow `<type>: <concise summary>` and keep each commit focused.

Pull requests should explain the user-visible effect, list manual Firefox checks, and link the relevant issue. Include screenshots for icons or browser-visible metadata. Explicitly call out permission, search URL, privacy, and packaging changes.

## Security & Privacy

Do not commit credentials or API keys. New permissions, telemetry, intermediary servers, or data collection require explicit justification and matching privacy documentation.

Permissions are deliberately limited to `storage`, `menus`, and `activeTab`,
which add no line to Firefox's install prompt. Do not add `tabs`,
`notifications`, `webNavigation`, or any host permission without re-reading
`docs/superpowers/specs/2026-07-29-extension-options-design.md` — each was
considered and rejected there, and Appendix B records a feature rejected on
security grounds that must not be revived without clearing the bar documented
with it.