Skip to content

AGENTS.md

Latest commit

 

History

History
61 lines (53 loc) · 4.05 KB

AGENTS.md

File metadata and controls

61 lines (53 loc) · 4.05 KB
Raw

AGENTS.md

Setup And Verification

  • Use Node.js 22 (the CI version) and npm; install from the lockfile with npm ci.
  • Always run npm run lint and npm run format:check. For code changes, also run npm test and npm run build; the build performs tsc -b before Vite.
  • Run one test file with npm test -- src/path/to/file.test.ts; add -t "test name" to select one case. Vitest uses its default Node environment, so mock chrome, window, and document with vi.stubGlobal as the existing tests do.
  • CI currently runs only lint and formatting. A green CI job does not verify tests, type-checking, or the extension build.
  • Prettier is authoritative: double quotes, semicolons, 4-space indentation, trailing commas, and 100-column lines.
  • TypeScript enables erasableSyntaxOnly and verbatimModuleSyntax; use type-only imports where required and avoid enums, parameter properties, and other non-erasable TypeScript syntax.

Entrypoints And Boundaries

  • src/manifest.ts is the development manifest and wires index.html (popup), options.html, src/background/service-worker.ts, and src/content/index.ts. Keep manifest changes mirrored in src/manifest.prod.ts when they apply to releases.
  • src/content/index.ts is a side-effect entrypoint: its imports register page listeners, analysis, the long-lived event-stream port, and the pet overlay. It runs with DOM access in Chrome's isolated content-script world.
  • src/background/service-worker.ts owns browser listeners, engine orchestration, persistence, AI calls, and runtime-message handlers. It is an MV3 service worker and must not use DOM APIs.
  • Popup and Options are independent React roots. Put shared UI/runtime wrappers in src/ui/; keep cross-context request/response types, unions, and type guards together in src/messages.ts.

Data And Privacy

  • Tracked events are interfaces under src/models/events/; extend Event or UiEvent and create instances with createEvent, which supplies timestamp and processed.
  • Options are one persisted chrome.storage.local record. Adding a field requires updating src/models/Option.ts, defaults and legacy normalization in src/services/OptionStore.ts, and its tests.
  • IndexedDB stores have independent DB_VERSION values in src/services/. Schema changes need a version bump and upgrade path for installed users; new persisted stores must also be cleared by the Settings page's clearAllData flow.
  • clearAllData currently removes the Option record and five IndexedDB stores, not auxiliary chrome.storage.local keys. Do not describe it as a complete reset unless that flow is expanded.
  • Use createLogger from src/utils/logger.ts; do not call console.* directly or log raw API keys, page HTML/Markdown, prompts, keystrokes, coordinates, DOM identifiers, or private URLs.
  • AI classification sends the full URL and page HTML-derived Markdown; AI daily reports send a structured activity/load summary. Both calls belong in the service worker. Keep the API key in extension storage/background code, never in the content script.
  • README.md is the single public product, privacy, permission, setup, and release document. Update it when collected or persisted fields, AI payloads, content-script matches, host permissions, retention/clear behavior, developer commands, or release behavior changes.

Builds And Releases

  • npm run build uses the development manifest and writes the ignored, unpacked extension to dist/. npm run preview cannot validate service workers, content scripts, or Chrome APIs; load dist/ through chrome://extensions and reload the extension after each rebuild.
  • npm run build-prod uses src/manifest.prod.ts, writes dist-prod/, and packages release/brainrest-x.y.z.zip. The packaging script requires production update_url and rejects a manifest key; debug/demo visibility depends on this distinction.
  • Keep the version synchronized in package.json, src/manifest.ts, and src/manifest.prod.ts. Do not edit or commit generated dist/, dist-prod/, or release/ contents.