diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..8aab7031 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# Repository Guidelines + +## Dos and Don'ts +- Do install dependencies with `yarn` (classic Yarn v1) after checkout so postinstall scripts set up Electron and Husky hooks correctly. +- Do run targeted Jest suites first, e.g. `yarn test app/lib/__tests__/loadThemes.spec.js`, before running the full suite. +- Do follow the existing two-space indentation and no-semicolon style when editing JavaScript/TypeScript files. +- Do reference existing Webpack aliases (e.g. `main/...`, `lib/...`, `plugins/...`) instead of rewriting import paths. +- Don't switch package managers or bump Node/Electron versions without coordinating updates to `package.json`, `electron-builder.json`, and CI workflows. +- Don't mass-reformat files or reorganize modules; keep diffs minimal and scoped to the task at hand. + +## Project Structure and Module Organization +- Electron app with React renderer lives under `app/`; `app/main` is the primary renderer UI, `app/background` handles background tasks, and `app/lib` hosts shared utilities. +- Core and external plugin logic resides in `app/plugins`; `app/plugins/core` contains built-in plugins and supporting helpers. +- Webpack, Babel, Jest, and TypeScript configs are defined at the repo root (`webpack.config.*.js`, `babel.config.js`, `jest.config.js`, `tsconfig.json`). +- Release assets, icons, and installer scripts live in `build/`; Electron Builder configuration is in `electron-builder.json`. +- Continuous Integration workflows that run tests and releases are under `.github/workflows/` (`pr.yml`, `build.yml`). +- Top-level entry points include `server.js` (hot-reload dev server) and `app/main.development.js` (Electron main process during development). + +## Build, Test, and Development Commands +- Install dependencies with `yarn`; this also runs `electron-builder install-app-deps` and enables Husky commit hooks. +- Launch the hot-reload development loop with `yarn dev` (spawns the Webpack hot server and a development Electron window). +- For production smoke tests run `yarn build` first (emits `app/main.js` and `app/dist` bundles), then launch Electron with `yarn start`. +- Build artifacts with `yarn build` (renders both main and renderer bundles) or package distributables with `yarn package` / `yarn release` as defined in `package.json`. +- Run focused Jest suites via `yarn test `; for example `yarn test app/main/actions/__tests__/search.spec.js` exercises action creators. The default `yarn test` executes all suites with coverage (`collectCoverage: true`). +- Linting uses ESLint with the Airbnb base: `yarn lint` runs against `app/background app/lib app/main app/plugins *.js`. Keep new code compliant and retain the inline suppressions where we forward plugin props (ResultsList rows, FormItem form controls). + +## Coding Style and Naming Conventions +- `.editorconfig` enforces spaces (size 2) for JavaScript/TypeScript and tabs elsewhere; trim trailing whitespace except in Markdown. +- ESLint (Airbnb rules) is the baseline; notable overrides include `semi: ['error', 'never']`, disabled dangling commas, and relaxed import extension checks. Maintain single quotes. Do not add new trailing commas; you may leave existing trailing commas in legacy code unchanged. +- Shared modules rely on Webpack/TypeScript path resolution (`app` treated as the module root). Preserve aliases like `import config from 'lib/config'` and directory `index.(js|ts)` entrypoints. +- React components primarily live in `app/main/components`, with styles handled via CSS modules (`*.module.css`). Follow existing patterns for component structure and CSS naming. +- Comments are short English line comments (`//`) or block comments where clarification is required; prefer matching the current files' commenting style. + +## Testing Guidelines +- Jest is configured via `jest.config.js` with coverage enabled and a custom module mapper for static assets and CSS; tests live alongside source in `__tests__` directories and `*.spec.js` files. +- Use `yarn test ` for scoped runs while iterating, then run `yarn test` before submitting to ensure coverage numbers stay intact. +- When adding UI logic, favor lightweight Jest tests around reducers, actions, or utilities; UI components typically rely on snapshot-free, behavior-focused tests. +- Tests rely on the Electron renderer environment; include `@jest-environment jsdom` when DOM APIs are needed, mirroring existing suites. + +## Commit and Pull Request Guidelines +- Conventional Commits are enforced by Husky + Commitlint (`.commitlintrc.json` extends `@commitlint/config-conventional`). Keep subjects imperative and under 50 characters when possible. +- Use `yarn commit` (Commitizen) if you need help crafting compliant messages; otherwise ensure manual commits follow the same format (`feat:`, `fix:`, `chore:` etc.). +- Keep pull requests focused and ensure `yarn test ` passes locally before pushing; CI (`.github/workflows/pr.yml`) re-runs `yarn` and `yarn test --detectOpenHandles --forceExit` on Ubuntu. +- Link related issues in PR descriptions and include screenshots/gifs when UI behavior changes, matching past contributions in the history. + +## Safety and Permissions +- Ask before adding dependencies, modifying build/CI configuration, or deleting/renaming files that affect Electron packaging or plugin contracts. +- Reading files, inspecting configs, and running scoped tests (`yarn test `) or targeted builds (`yarn build-main`) are safe by default. +- Avoid destructive git operations, manual cleanups in `release/`, or editing generated bundles under `app/dist`; regenerate via the provided scripts instead. +- Do not store secrets or environment credentials in the repo; follow `.env.example` when local overrides are required.