browser/.github/copilot-instructions.md

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