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.