diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b55288c4..cec158aa 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,6 +4,8 @@ This is the **Power Platform VS Code extension** that provides tooling for creating, building, and deploying Power Platform solutions, packages, and portals. It integrates the Power Platform CLI (pac) directly into VS Code. +Always refer to [memory-bank.instructions.md](instructions/memory-bank.instructions.md) for the latest architecture and coding guidelines. + ### Key Components - **Client (`src/client/`)**: Main VS Code extension logic, UI components, and Power Pages tooling @@ -22,21 +24,24 @@ This is the **Power Platform VS Code extension** that provides tooling for creat ## Development Workflows ### Build Commands + - `npm run build` or `gulp`: Full build (uses gulpfile.mjs) - `npm run compile-web`: Build web version only - `npm run test-desktop-int`: Run desktop integration tests - `npm run test-web-integration`: Run web integration tests ### Key Files for Extension Development + - `src/client/extension.ts`: Main extension entry point - `package.json`: Extension manifest with commands and contributions - `src/client/lib/PacActivityBarUI.ts`: Activity bar panels and UI registration - `src/client/PortalWebView.ts`: Power Pages portal webview management - `src/client/pac/PacWrapper.ts`: Wrapper for Power Platform CLI commands - `src/client/power-pages/actions-hub/ActionsHubTreeDataProvider.ts`: Power Pages Actions Hub tree data provider -- +- ### PAC CLI Integration Patterns + ```typescript // Always use PacWrapper for CLI operations const pacWrapper = new PacWrapper(context); @@ -46,40 +51,47 @@ await pacWrapper.executeCommand(['solution', 'list']); ## Coding Guidelines ### Indentation & Style + - Use 4 spaces for indentation (no tabs) - Arrow functions `=>` over anonymous functions - Curly braces on same line, always use braces for loops/conditionals - No whitespace in parenthesized constructs: `for (let i = 0; i < 10; i++)` ### Naming Conventions + - PascalCase: `type` names, `enum` values - camelCase: `function`/`method` names, `property` names, `local variables` - UPPER_CASE: constants - Use whole words when possible ### Strings & Localization + - "double quotes" for user-facing strings that need localization - 'single quotes' for internal strings - All user-visible strings MUST be externalized using `vscode-nls` ### Comments + - Use JSDoc style comments for functions, interfaces, enums, and classes - Include parameter descriptions and return types ## Testing Patterns ### Framework Usage + - **Mocha** test framework with `describe` and `it` blocks - **Chai** `expect` assertions (not assert) - **Sinon** for stubs and spies - Mock dependencies extensively for unit tests ### Test Organization + - Unit tests: `src/*/test/unit/` - Integration tests: `src/*/test/integration/` - No `//Arrange`, `//Act`, `//Assert` comments ### Running Tests + ```bash npm run test # Unit tests npm run test-desktop-int # Desktop integration tests @@ -89,16 +101,19 @@ npm run test-web-integration # Web integration tests ## Power Platform Specific Patterns ### Power Pages Development + - Portal files use specific extensions: `.copy.html`, `.custom_javascript.js` (see `src/common/constants.ts`) - File system callbacks in `src/client/power-pages/fileSystemCallbacks.ts` - Bootstrap diff functionality for portal template updates ### CLI Version Management + - CLI versions managed in `src/client/lib/CliAcquisition.ts` - Global storage for CLI binaries in VS Code's global storage path - Cross-platform support (Windows `.exe`, Unix executables) ### Telemetry Implementation + - Use `oneDSLoggerWrapper` for all telemetry events - Events defined in `src/common/OneDSLoggerTelemetry/telemetryConstants.ts` - Separate telemetry for desktop vs web experiences diff --git a/.github/instructions/desktop-extension.instructions.md b/.github/instructions/desktop-extension.instructions.md new file mode 100644 index 00000000..ff17dc08 --- /dev/null +++ b/.github/instructions/desktop-extension.instructions.md @@ -0,0 +1,62 @@ +--- +applyTo: src/client/** +description: Desktop Extension Setup and Contribution Instructions +--- + +# VS Code Desktop Extension + +## 1. Project Overview + +- The Power Platform VS Code extension desktop code is under `src/client/`. +- Key files: `src/client/extension.ts` (entry), `package.json` (manifest), `src/client/lib/` (CLI integration), `src/client/power-pages/` (Power Pages tooling). + +## 2. Development Environment + +- Node.js 18+ and npm 9+ required. +- Install dependencies: `npm install` +- Build extension: `gulp ci` +- Test extension: `npm run test-desktop-int` +- Debug/launch in VS Code using provided launch configs. + +## 3. Coding Standards + +- TypeScript, 4-space indentation, arrow functions preferred. +- Externalize all user-facing strings with `vscode-nls`. +- PascalCase for types/enums, camelCase for functions/variables. +- JSDoc comments for exported functions, classes, interfaces. + +## 4. Key Architectural Patterns + +- **PAC CLI Integration:** Use `PacWrapper` for CLI operations. +- **Telemetry:** Use `oneDSLoggerWrapper` for events. +- **Service Architecture:** Core services in `src/common/services/`. + +## 5. Testing + +- Unit tests: `npm run test` +- Integration tests: `npm run test-desktop-int` +- Use Mocha, Chai, Sinon. Mock dependencies. + +## 6. Contribution Workflow + +- Fork and clone repo. Create feature branch from `main`. +- Make changes in `src/client/` for desktop features. +- Cover new code with tests. Run all tests before PR. +- Submit PR with clear description. + +## 7. Localization + +- Update localization files in `l10n/` and `localize/` as needed. +- Add new strings to `package.nls.json`. + +## 8. Common Tasks + +- Add commands: update `package.json`, implement in `src/client/extension.ts`. +- PAC CLI: use `PacWrapper`. +- Telemetry: use `oneDSLoggerWrapper`. +- UI: update files in `src/client/` and assets in `src/client/assets/`. + +## 9. Reference Docs + +- See `.github/copilot-instructions.md` for architecture/coding guidelines. +- See `README.md` for project info. diff --git a/.github/instructions/directoryStructure.instructions.md b/.github/instructions/directoryStructure.instructions.md index 32cb23d6..e025ff29 100644 --- a/.github/instructions/directoryStructure.instructions.md +++ b/.github/instructions/directoryStructure.instructions.md @@ -1,4 +1,5 @@ --- +applyTo: "**" description: Directory Structure Overview --- Provide a brief overview of the directory structure for the Power Platform VS Code extension. This will help in understanding where to find specific components and how the project is organized. diff --git a/.github/instructions/web-extension.instructions.md b/.github/instructions/web-extension.instructions.md new file mode 100644 index 00000000..f1217491 --- /dev/null +++ b/.github/instructions/web-extension.instructions.md @@ -0,0 +1,119 @@ +--- +applyTo: "src/web/**" +description: Web Extension Setup and Contribution Instructions +--- + +# Web Extension Instructions + +This document provides setup, architecture, coding, and testing instructions for the web extension located in `src/web`. It is designed to help both humans and AI agents contribute effectively. + +## Table of Contents + +- [Overview](#overview) +- [Architecture](#architecture) +- [Installation](#installation) +- [Development](#development) +- [Folder Structure](#folder-structure) +- [Coding Guidelines](#coding-guidelines) +- [Building the Extension](#building-the-extension) +- [Testing](#testing) +- [Power Platform Patterns](#power-platform-patterns) +- [Contributing](#contributing) +- [Troubleshooting](#troubleshooting) + +## Overview + +The web extension extends Visual Studio Code for Power Platform scenarios. All source code for the web extension is located in the `src/web` directory. + +## Architecture + +- **Client (`src/web/client/`)**: Main VS Code web extension logic and UI components. +- **Common (`src/common/`)**: Shared utilities, telemetry, and services. +- **Multi-Target Build**: Uses webpack for desktop, web, and language servers. +- **Telemetry**: Uses OneDSLogger for web telemetry (`src/common/OneDSLoggerTelemetry/`). +- **Service Architecture**: Core services in `src/common/services/`. +- **Entrypoint**: `src/web/client/extension.ts` is the main entry point for the web extension. + +## Installation + +1. Ensure you have [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed. +2. Navigate to the project root directory: + + ```sh + cd /path/to/powerplatform-vscode + ``` + +3. Install dependencies: + + ```sh + npm install + ``` + +## Development + +- Main code for the web extension is inside `src/web/client/`. +- Open the project in Visual Studio Code. +- Make changes in the `src/web/client/` directory as needed. +- For CLI operations, use the `PacWrapper` abstraction. + +## Folder Structure + +```text +src/ +└── web/ + └── client/ +``` + +- `client/`: Contains the client-side code for the web extension. + +## Coding Guidelines + +- **Indentation**: 4 spaces, no tabs. +- **Arrow functions**: Prefer `=>` over anonymous functions. +- **Braces**: Always use braces for loops/conditionals, on the same line. +- **Naming**: PascalCase for types/enums, camelCase for functions/properties/variables, UPPER_CASE for constants. +- **Strings**: "double quotes" for user-facing strings (externalized via `vscode-nls`), 'single quotes' for internal strings. +- **Comments**: Use JSDoc style for functions, interfaces, enums, and classes. +- **Localization**: All user-visible strings must be externalized. + +## Building the Extension + +To build the web extension, run: + +```sh +gulp ci +``` + +This will compile the extension and output the necessary files. + +## Testing + +- **Unit tests**: Located in `src/web/client/test/unit/` +- **Integration tests**: Located in `src/web/client/test/integration/` +- **Frameworks**: Mocha (describe/it), Chai (expect), Sinon (stubs/spies) +- **Running tests**: + + ```sh + npm run test-web-integration + ``` + +- Mock dependencies extensively for unit tests. + +## Power Platform Patterns + +- **Telemetry**: Use `oneDSLoggerWrapper` for all events, defined in `src/common/OneDSLoggerTelemetry/telemetryConstants.ts`. + +## Contributing + +1. Fork the repository and create a new branch for your feature or bugfix. +2. Make your changes in `src/web/client/` and, if needed, in `src/common/` for shared utilities and services which can be used across web and desktop. +3. Follow coding and testing guidelines above. +4. Submit a pull request with a clear description of your changes. +5. The main difference between web and desktop extension is that desktop extension runs in a Node.js environment, while the web extension runs in a browser-like environment. This affects how certain APIs and modules can be used. + +## Troubleshooting + +- Ensure your Node.js and npm versions are up to date. +- Check for missing dependencies in `package.json`. +- Review error messages in the terminal for guidance. +- For build/test issues, consult architecture and coding guidelines above.