Skip to content

AGENTS.md

Latest commit

 

History

History
69 lines (55 loc) · 6.1 KB

AGENTS.md

File metadata and controls

69 lines (55 loc) · 6.1 KB

Repository Guidelines

Dos and Don’ts

  • Do align your Node.js runtime with .nvmrc via nvm use before running repo scripts.
  • Do install dependencies with npm install (or npm ci in clean environments) so that the postinstall electron dependencies stay in sync.
  • Do run npm run lint -- src/<relative-file> and npx prettier --check <relative-file> on every touched file (for example, npm run lint -- src/main.js).
  • Do keep locale files in src/i18n/locales/ and prompt catalogs in src/prompts/ updated whenever UI strings change.
  • Don't commit generated artifacts such as dist_electron/ outputs or transient logs; rebuild them locally when needed.
  • Don't change shared configuration (package.json, vue.config.js, CI workflows) or add dependencies without first confirming the impact.

Project Structure and Module Organization

  • ChatALL is a Vue 3 + Vuetify 3 desktop app packaged with Electron via vue-cli-plugin-electron-builder.
  • src/main.js, src/App.vue: bootstraps Vuetify, Vuex, i18n, Matomo analytics, and Electron IPC wiring.
  • src/background.js: runs the Electron main process, wiring BrowserWindow lifecycle, proxy handling, and single-instance guard.
  • src/bots/: contains every bot connector plus registration logic in src/bots/index.js; use TemplateBot.js when adding new integrations.
  • src/components/, src/composables/, src/helpers/: Vue components, reusable composition utilities, and helper functions.
  • src/store/: Vuex state management modules and persistence helpers.
  • src/i18n/index.js and src/i18n/locales/*.json: localization setup and language packs (fallback en).
  • src/prompts/: canned prompt definitions aligned with locale files.
  • src/assets/ and public/: ships product icons, base HTML shell, and provider logos under public/bots/.
  • .github/workflows/*.yml: CI pipelines for deploy (deploy.yml), release packaging (release.yml), and GitHub Pages sync (static.yml).
  • vue.config.js: centralizes Vue CLI and Electron Builder configuration; double-check implications before changing it.
  • dist_electron/: Electron build artifacts generated by npm run electron:build (ignored by version control).

Build, Test, and Development Commands

  • Scripts live in package.json; ensure dependencies are installed before running them.
  • npm install / npm ci: install JavaScript and Electron dependencies (triggers electron-builder install-app-deps).
  • npm run electron:serve: launch the Electron development build with hot reload.
  • npm run build: produce the web build in dist/; used by .github/workflows/deploy.yml.
  • npm run electron:build: package the desktop app for the current platform; npm run release-<platform> wraps platform-specific release builds.
  • npm run lint -- src/<relative-file>: run ESLint + Prettier checks on specific files (for example, npm run lint -- src/main.js).
  • npx prettier --check <relative-file>: confirm formatting per .prettierrc.js; npm run format writes the entire src/ tree when broad formatting is necessary.
  • npm run start: open the packaged app from the current workspace using the locally built files.

Coding Style and Naming Conventions

  • Prettier (.prettierrc.js) enforces semicolons, double quotes, two-space indentation, and 80-character line width; always format through Prettier rather than manual spacing.
  • ESLint extends plugin:vue/vue3-essential, eslint:recommended, and plugin:prettier/recommended; resolve lint warnings instead of suppressing them.
  • Follow existing naming: camelCase for functions/variables, PascalCase for Vue components and classes, consistent with CONTRIBUTION.md.
  • Use the @/ alias (configured in jsconfig.json) instead of deep relative paths when importing from src/.
  • Keep code comments and implementation notes in English, and add concise comments only when logic is non-obvious.
  • When adding a bot, base it on src/bots/TemplateBot.js, register it in src/bots/index.js, and update any applicable botTags entries.
  • Update src/i18n/locales/*.json and matching prompt files whenever new user-facing text or actions are introduced.

Testing Guidelines

  • The project has no automated unit test suite; rely on linting, builds, and manual verification.
  • Use npm run lint -- src/<relative-file> and npx prettier --check <relative-file> as fast feedback loops before committing changes.
  • For functional validation, run npm run electron:serve to exercise UI and bot flows; when packaging logic changes, run npm run electron:build.
  • After altering persistence (src/store/ or migrations), launch the app to confirm data migrations and settings behave as expected.

Commit and Pull Request Guidelines

  • Follow CONTRIBUTION.md: keep pull requests focused, update localization files for any UI copy changes, and avoid mixing unrelated refactors with features.
  • Use imperative, concise commit subjects similar to recent history (Update dependencies, Remove deprecated Mixtral8x7b APIBot via Groq), optionally with conventional prefixes (fix:) when appropriate.
  • Run the repo’s linting and formatting commands before committing; husky’s pre-commit hook (.husky/pre-commit) already invokes npx lint-staged on staged Vue/JS files.
  • Reference related issues or PR numbers in commit bodies when applicable, mirroring existing commits that include (#id) annotations.
  • Include context in PR descriptions (screenshots for UI changes, reproduction steps for bug fixes) to streamline reviews.

Safety and Permissions

  • Favor minimal, file-scoped edits that respect the current formatting; never run broad reformatting across the codebase without approval.
  • It is safe to read/list files, modify code under src/, and run targeted lint/format/build commands documented above.
  • Seek confirmation before adding dependencies, altering build/release configuration, or deleting/renaming files.
  • Avoid committing secrets, API keys, or personal data; configuration lives in user settings and should remain local.
  • Coordinate on large architectural changes or cross-cutting refactors before implementation to prevent drift from project expectations.