diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..06060f0c5cb --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,109 @@ +This document provides explicit instructions for Copilot Agent to follow when working with this +repository. It outlines the coding standards, project structure, and best practices to ensure +high-quality contributions that align with the repository's goals and maintainability standards. + +## Repository Overview + +This repository is organized as a **monorepo** containing multiple applications and libraries. The +main directories are: + +- `apps/` – Contains all application projects (e.g., browser, cli, desktop, web). Each app is + self-contained with its own configuration, source code, and tests. +- `libs/` – Contains shared libraries and modules used across multiple apps. Libraries are organized + by domain or functionality (e.g., common, ui, platform, key-management). + +**Strict boundaries** must be maintained between apps and libraries. Do not introduce +cross-dependencies that violate the intended modular structure. Always consult and respect the +dependency rules defined in `eslint.config.mjs`, `nx.json`, and other configuration files. + +## Coding Standards and Best Practices + +### 1. Linting and Formatting + +- All code **must** pass ESLint and Prettier checks before being committed. +- Use the provided configuration files (`eslint.config.mjs`, `.prettierrc`, etc.). +- **Do not** override or disable linting/formatting rules unless explicitly instructed by repository + maintainers. +- Run linting and formatting tools locally before submitting changes. + +### 2. TypeScript Usage + +- Use **strict typing** throughout the codebase. Avoid the use of `any` unless absolutely necessary + and justified with a comment. +- Adhere to the settings in `tsconfig.json` and `tsconfig.eslint.json`. +- Prefer interfaces and type aliases for type definitions. Use enums and literal types where + appropriate. +- Always annotate function return types and exported members. + +### 3. Project Structure and File Organization + +- Place all source code for apps in their respective `src/` directories within `apps/`. +- Place all source code for libraries in their respective `src/` directories within `libs/`. +- Tests should be located in alongside the code in `*.spec.ts` files, following the conventions of + each app or library. +- Do not place unrelated files or code in shared directories. +- Keep configuration files (e.g., `jest.config.js`, `tsconfig.json`) at the root of each app or + library. + +### 4. Testing + +- All new features and bug fixes **must** include appropriate unit and/or integration tests. +- Use Jest for unit tests. +- Ensure all tests pass before submitting changes. +- Write clear, descriptive test names and use test coverage tools to ensure code is well-tested. + +### 5. Commit Messages + +- Use the **conventional commit** format for all commits. Example: + `feat(browser): add autofill support for new form type`. +- Prefix commits with `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, etc., as appropriate. +- Include a clear, concise description of the change and reference related issues when applicable. + +### 6. Security + +- **Never** commit secrets, credentials, or sensitive information. Follow the guidelines in + `SECURITY.md`. +- Review code for potential security vulnerabilities, especially when handling authentication, + encryption, or user data. +- Use environment variables and secure storage for sensitive configuration. + +### 7. Documentation + +- Update `README.md` or other relevant documentation files when making significant changes, adding + new features, or modifying existing behavior. +- Document public APIs, exported functions, and complex logic with clear comments and docstrings. +- Maintain up-to-date usage instructions and examples for each app and library. + +### 8. Dependency Management + +- Use `npm` for installing and managing dependencies. Do not use `yarn` or other package managers + unless specified. +- Do not add or update any dependencies unless explicitly asked. +- Do not modify `package.json` or `package-lock.json` unless required for the task. +- Only the root `package.json` should be modified for adding new dependencies. + +### 9. Configuration and Tooling + +- Respect all configuration files at the root and within each app/library (e.g., + `eslint.config.mjs`, `jest.config.js`, `tsconfig.json`). +- Do not override or duplicate configuration unless required for a specific app or library. +- Use provided scripts in `package.json` for building, testing, and linting. + +### 10. Communication and Collaboration + +- For questions, clarifications, or proposing significant changes, refer to `CONTRIBUTING.md` or + contact the repository maintainers. +- Open issues or pull requests with detailed descriptions and context. +- Review and address feedback promptly. + +## Summary Checklist for Copilot Agent + +- [ ] Respect monorepo structure and boundaries +- [ ] Pass all linting and formatting checks +- [ ] Use strict TypeScript typing +- [ ] Add/update tests for all changes +- [ ] Follow conventional commit messages +- [ ] Do not commit secrets or sensitive data +- [ ] Update documentation as needed +- [ ] Use npm for dependencies and do not modify lockfiles unnecessarily +- [ ] Adhere to all configuration and tooling standards