Add Copilot agent skills and expand contributor instructions (#4863)

* improve copilot agent setup: instructions, prompts, and ci environment

* add skills for adding commands, diagnostic parsers, settings, backend tests, and handling presets vs kits

* clarify Copilot CI environment instructions and improve command registration guidance

---------

Co-authored-by: Hannia Valera <hanniavalera@users.noreply.github.com>

Author: hanniavalera

.github/copilot-instructions.md

@@ -18,8 +18,11 @@ applyTo: "**/*.ts,**/*.tsx,**/package.json,**/*.cmake,**/CMakeLists.txt,**/CMake
 
 ## Project conventions
 
-- **Path alias**: `@cmt/*` maps to `src/*` (see `tsconfig.json`). Always use `import foo from '@cmt/foo'` — never relative paths from outside `src/`.
-- **Error reporting**: Use `rollbar.invokeAsync()` / `rollbar.invoke()` for top-level error boundaries around event handlers, never bare `try/catch` that silently swallows.
+- **Path alias**: `@cmt/*` maps to `src/*` (see `tsconfig.json`). Always use `import foo from '@cmt/foo'` — never relative paths from outside `src/`. `@test/*` maps to `test/*` (defined in both `tsconfig.json` and `test.tsconfig.json`). Use `import ... from '@test/...'` in test files.
+- **Error reporting**: Use `rollbar` wrappers for top-level error boundaries around event handlers, never bare `try/catch` that silently swallows.
+  - `rollbar.invoke(what, fn)` — wraps synchronous code; catches, logs, and re-throws.
+  - `rollbar.invokeAsync(what, fn)` — wraps async function execution; catches promise rejections.
+  - `rollbar.takePromise(what, additional, thenable)` — attaches an error handler to an **already-created** Thenable (e.g., a return value from a VS Code API call). Use this when you have a promise but didn't create it via `invokeAsync`.
 - **Telemetry**: Use helpers in `src/telemetry.ts` (`logEvent`). Never call the VS Code telemetry API directly.
 
 ## Architecture
@@ -58,14 +61,41 @@ Identify the affected layer(s) from the architecture table above. Read the relev
 | Cache entries | `CMakeDriver.cmakeCacheEntries` |
 | Extension settings | `ConfigurationReader` (`src/config.ts`) — never `vscode.workspace.getConfiguration()` directly |
 
+### Reactive configuration subscriptions
+
+Use `ConfigurationReader.onChange()` for typed, per-setting change notifications:
+
+```typescript
+const disposable = config.onChange('settingName', (newValue) => {
+    // Respond to change
+});
+// Store disposable in a field or push to a disposables array for cleanup
+```
+
+Do **not** use `vscode.workspace.onDidChangeConfiguration` directly — the `onChange()` API is type-safe, fires only for the specific setting, and integrates with the extension's promise tracking.
+
 ### Always handle both operating modes
 
 When a code path touches shared logic (configure, build, test, targets, environment), check `CMakeProject.useCMakePresets` and ensure it works correctly in both presets mode and kits/variants mode. Omitting the check for one mode in shared code is a bug waiting to happen. Features that are inherently mode-specific (e.g., kit scanning, preset expansion) are fine to scope to one mode.
 
+### `SpecialKits` sentinel values
+
+Kit names may be sentinel values, not real compiler paths. Always check before treating `kit.name` as a file path:
+
+- `SpecialKits.Unspecified` (`'__unspec__'`) — no kit selected
+- `SpecialKits.ScanForKits` (`'__scanforkits__'`) — triggers kit scanning
+- `SpecialKits.ScanSpecificDir` (`'__scan_specific_dir__'`) — scan a specific directory
+
+### Kit trust model
+
+Kits have an `isTrusted: boolean` property. Auto-scanned kits from untrusted paths are filtered out before selection and use. This prevents untrusted kits from executing `environmentSetupScript`. Do not bypass this trust filtering when adding kit-related code.
+
 ### Always handle both generator types
 
 Single-config uses `CMAKE_BUILD_TYPE`; multi-config uses `--config` at build time. Check the active generator before any build-type logic.
 
+Call `util.isMultiConfGeneratorFast(generator)` before any build-type logic. Multi-config generators include Visual Studio, Xcode, and Ninja Multi-Config. Note: the `cmake.setBuildTypeOnMultiConfig` setting can override multi-config behavior — check it before assuming.
+
 ### Localize all user-visible strings
 
 Every file with user-visible text needs the `vscode-nls` boilerplate:
@@ -79,6 +109,14 @@ const localize: nls.LocalizeFunc = nls.loadMessageBundle();
 // ❌ bare strings in user-visible output
 ```
 
+### NLS key naming and `package.nls.json`
+
+Settings: `cmake-tools.configuration.cmake.<settingName>.description` (or `.markdownDescription`)
+Commands: `cmake-tools.command.cmake.<commandName>.title`
+
+- Update `package.nls.json` for English strings — **never** modify files under `i18n/` (translations are updated separately).
+- When a setting uses `markdownDescription` in `package.json`, the NLS key suffix must be `.markdownDescription`, not `.description`.
+
 ### Use the module-scoped logger — never `console.log`
 
 ```typescript
@@ -98,10 +136,35 @@ Never concatenate path strings with `/` or `\\`. No exceptions.
 
 `package.json` (`contributes.configuration`), `src/config.ts` (`ConfigurationReader`), and `docs/cmake-settings.md`.
 
+### Setting `scope` in `package.json`
+
+Every setting in `contributes.configuration` must have an explicit `scope`:
+- `"resource"` — per-folder; use for anything CMake project-specific (paths, build args, generator, environment).
+- `"window"` — global; use for extension-wide UI/behavior settings.
+
+Examples: `cmake.buildDirectory` → `"resource"` (project-specific path), `cmake.autoSelectActiveFolder` → `"window"` (global UI behavior).
+
 ### Every PR needs a CHANGELOG entry
 
 One entry under the current version in `CHANGELOG.md`, in the appropriate section (`Features:`, `Improvements:`, or `Bug Fixes:`), describing user-visible behavior in the repo's existing tense and category style.
 
+### Adding a new diagnostic parser
+
+1. Create `src/diagnostics/<name>.ts` — extend `RawDiagnosticParser`, implement `handleLine()`
+2. Add an instance to the `Compilers` class in `src/diagnostics/build.ts`
+3. Add the parser name to `cmake.enabledOutputParsers` enum array **and** default array in `package.json`
+4. Add English strings to `package.nls.json` if descriptions change
+
+Currently registered: gcc, gnuld, ghs, diab, msvc, iar, iwyu. Default-enabled: cmake, gcc, gnuld, msvc, ghs, diab.
+
+### Copilot CI environment (agent-only)
+
+> **This section applies to the Copilot coding agent, not human contributors.**
+
+In the Copilot agent CI environment, `.npmrc` is renamed to `.npmrc.bak` and `yarn.lock` registry URLs are patched to use the public npm registry. These are environment artifacts:
+- **Never commit** `.npmrc.bak` or the patched `yarn.lock`
+- If `git status` shows these as modified, run `git checkout -- .npmrc yarn.lock` before committing
+
 ## Testing checklist
 
 - [ ] `yarn unitTests` passes
@@ -111,6 +174,20 @@ One entry under the current version in `CHANGELOG.md`, in the appropriate sectio
 - [ ] Behavior verified with **single-config** and **multi-config** generators
 - [ ] Windows/macOS/Linux differences considered (paths, env vars, MSVC toolchain, generator availability)
 
+### Backend tests (`yarn backendTests`)
+
+The fastest feedback loop — runs via Mocha with no VS Code instance or display required.
+
+- **Files go in** `test/unit-tests/backend/<name>.test.ts`
+- **Framework:** Mocha TDD (`suite`/`test`), Chai `expect` assertions
+- **Run:** `yarn backendTests`
+- **Mock setup:** `test/unit-tests/backend/setup-vscode-mock.ts` provides minimal `vscode` stubs
+
+**Import strategy:**
+1. If the module has **no transitive `vscode` dependency** (e.g., `encodingUtils`, `cmakeValue`) → import directly via `@cmt/*`
+2. If the module **transitively imports `vscode`** and the mock is insufficient → **mirror the pure function logic inline** in the test file. This is the established pattern in `expand.test.ts`, `targetMap.test.ts`, `shell-propagation.test.ts`.
+3. **Heuristic:** Try `@cmt/*` import first. If it fails due to vscode dependency at runtime, fall back to mirroring.
+
 ## Where to start
 
 - **Configure/build/test behavior** → `src/cmakeProject.ts` + `src/drivers/`

.github/skills/add-command/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: add-command
+description: >
+  Use when adding a new cmake.* command to CMake Tools. Touches package.json
+  (contributes.commands), package.nls.json, src/extension.ts (funs array), and
+  CHANGELOG.md. Triggers: "add command", "register command", "new command palette entry".
+---
+
+# Adding a New Command
+
+Recipe for adding a new `cmake.*` command to CMake Tools.
+
+## Files you must touch
+
+| File | What to add |
+|------|-------------|
+| `package.json` | Command declaration in `contributes.commands` + optional menu entries |
+| `package.nls.json` | English title string |
+| `src/extension.ts` | Method name in `funs` array + handler method on `ExtensionManager` |
+| `CHANGELOG.md` | Entry under the current version |
+
+---
+
+## Step 1 — Declare the command in `package.json`
+
+### 1a — `contributes.commands`
+
+```jsonc
+// package.json  →  contributes.commands
+{
+  "command": "cmake.myCommand",
+  "title": "%cmake-tools.command.cmake.myCommand.title%",
+  "category": "CMake"
+}
+```
+
+### Rules
+
+- **Command ID format:** `cmake.<commandName>` (camelCase).
+- **Title:** NLS key in the format `%cmake-tools.command.cmake.<commandName>.title%`.
+- **Category:** `"CMake"` — this prefixes the title in the Command Palette as `CMake: <title>`.
+- **`when`** (optional): controls when the command appears in the Command Palette.
+- **`icon`** (optional): Codicon reference like `"$(settings-gear)"` for tree-view inline buttons.
+
+### 1b — `contributes.menus` (if needed)
+
+Add visibility rules for where the command appears.
+
+**Command Palette visibility:**
+
+```jsonc
+// package.json  →  contributes.menus.commandPalette
+{
+  "command": "cmake.myCommand",
+  "when": "cmake:enableFullFeatureSet"
+}
+```
+
+**Sidebar tree-view inline button:**
+
+```jsonc
+// package.json  →  contributes.menus["view/item/context"]
+{
+  "command": "cmake.projectStatus.myCommand",
+  "when": "view == cmake.projectStatus && cmake:enableFullFeatureSet && viewItem == 'myItem'",
+  "group": "inline"
+}
+```
+
+Common `when` clause patterns:
+
+| Pattern | Meaning |
+|---------|---------|
+| `cmake:enableFullFeatureSet` | Extension is fully activated |
+| `useCMakePresets` | Presets mode is active |
+| `!useCMakePresets` | Kits/variants mode is active |
+| `view == cmake.projectStatus && viewItem == 'kit'` | Specific tree-view item |
+| `viewItem =~ /configPreset/` | Regex match on tree-view item |
+
+---
+
+## Step 2 — Add the English string to `package.nls.json`
+
+```json
+"cmake-tools.command.cmake.myCommand.title": "My Command Title"
+```
+
+For titles containing the product name, use the object form with a translator comment:
+
+```json
+"cmake-tools.command.cmake.myCommand.title": {
+  "message": "Do Something with CMake Tools",
+  "comment": ["The text 'CMake Tools' should not be localized."]
+}
+```
+
+> **Do not** modify any file under `i18n/`.
+
+---
+
+## Step 3 — Register the command in `src/extension.ts`
+
+Add the method name to the `funs` array (search for `const funs:` near the end of the file). The `register()` helper
+auto-generates the command ID `cmake.<name>`, wraps it with debug logging, and hands
+the promise to `rollbar.takePromise()` for error tracking.
+
+```typescript
+// src/extension.ts
+const funs: (keyof ExtensionManager)[] = [
+    // ... existing entries ...
+    'myCommand',   // ← add here
+];
+```
+
+That's it — no manual `registerCommand` call needed. The loop that follows handles registration automatically:
+
+```typescript
+for (const key of funs) {
+    context.subscriptions.push(register(key));
+}
+```
+
+> Only use manual `vscode.commands.registerCommand()` for commands that need
+> custom argument handling (e.g., tree-view context-menu commands that receive
+> a node argument). Most commands go through the `funs` array.
+
+---
+
+## Step 4 — Implement the handler on `ExtensionManager`
+
+Add a method to the `ExtensionManager` class in `src/extension.ts`. The method
+name must match the string added to the `funs` array.
+
+### Pattern A — Delegate to CMakeProject (most common)
+
+```typescript
+myCommand(folder?: vscode.WorkspaceFolder) {
+    telemetry.logEvent('myCommand');
+    return this.runCMakeCommand(
+        cmakeProject => cmakeProject.myCommand(),
+        folder,
+        undefined, // precheck (optional)
+        true       // cleanOutputChannel
+    );
+}
+```
+
+Then implement the actual logic on `CMakeProject` in `src/cmakeProject.ts`.
+
+### Pattern B — Run for all projects
+
+```typescript
+myCommandAll() {
+    telemetry.logEvent('myCommand', { all: 'true' });
+    return this.runCMakeCommandForAll(
+        cmakeProject => cmakeProject.myCommand()
+    );
+}
+```
+
+### Pattern C — Direct implementation (no CMakeProject delegation)
+
+```typescript
+async myCommand() {
+    telemetry.logEvent('myCommand');
+    const result = await vscode.window.showQuickPick(items);
+    if (!result) {
+        return;
+    }
+    // ... handle result ...
+}
+```
+
+### Key helpers
+
+| Helper | Use when |
+|--------|----------|
+| `this.runCMakeCommand(cmd, folder)` | Single-project command |
+| `this.runCMakeCommandForAll(cmd)` | Runs on every open CMake project |
+| `this.runCMakeCommandForProject(cmd, project)` | Specific project instance |
+
+---
+
+## Step 5 — Add a CHANGELOG entry
+
+Add an entry under the current version in `CHANGELOG.md`, in the `Features:` section.
+
+---
+
+## Verification checklist
+
+- [ ] `package.json` — command declared with NLS title and `"CMake"` category
+- [ ] `package.json` — menu entries added (if applicable) with correct `when` clauses
+- [ ] `package.nls.json` — English title string added
+- [ ] `src/extension.ts` — method name added to `funs` array
+- [ ] `src/extension.ts` — handler method implemented on `ExtensionManager`
+- [ ] Handler uses `telemetry.logEvent()` for telemetry
+- [ ] Handler delegates to `CMakeProject` via `runCMakeCommand` (if project-scoped)
+- [ ] `CHANGELOG.md` — entry added
+- [ ] `yarn compile` succeeds
+- [ ] No files under `i18n/` were modified
+
+---
+
+*See also: [`.github/copilot-instructions.md`](../copilot-instructions.md) for project-wide conventions.*