CLI-366 SQAA workaround for copilot integration

[tomshafir-sonarsource]

[hashicorp-vault-sonar-prod]

CLI-366

[sonar-review-alpha]

Summary

This PR adds SonarQube Agentic Analysis (SQAA) support to Copilot integration. It extends the CLI's custom instructions to include directives that trigger sonar analyze agentic at end-of-turn for modified files, alongside the existing prompt-secrets warnings.

Key changes:

• Instructions now contain two sections: prompt-secrets (existing) and SQAA (new, conditional)
• Instructions file is now CLI-owned and rewritten on every run (no skip-on-existing-global logic)
• SQAA installs only when org is entitled, project key is available, and auth is cloud
• State tracking split: instructionsInstalled → promptSecretsInstructionsInstalled + sqaaInstructionsInstalled (with cloud metadata)
• Global installs can have prompt-secrets globally and SQAA project-scoped when a project key is discoverable
• Added MCP server configuration file (.mcp.json)

What reviewers should know

Where to start:

• Read src/cli/commands/integrate/copilot/instructions.ts first to understand the two instruction sections and how they're composed
• Then index.ts to see the entitlement check (resolveSqaaProjectKey) and orchestration
• Finally state.ts to understand the new schema for tracking both sections separately

Non-obvious decisions:

1. CLI-owned file: The instructions file is no longer skipped when a global version exists — both global and project files can coexist with different content. This is intentional; the file is "CLI-owned" and rewritten fresh each run.
2. SQAA is always project-scoped: Even integrate copilot -g can write SQAA to a project file (under .github/instructions/) when a project key is discovered from sonar-project.properties. The prompt-secrets section goes global, SQAA goes project.
3. Idempotency: Running the command twice produces no duplicate sections (file is fully rewritten, not appended to). Tests verify this.
4. Scope mismatch tolerance: An orphan warning surfaces if a global instructions file exists when installing project-level (the global file is left untouched).

Things to watch:

• Entitlement check (resolveSqaaProjectKey): Runs a real API call; failures are logged as warnings and SQAA is skipped gracefully
• Auth requirement: SQAA requires cloud auth with organization; on-premise deployments silently skip it
• Test coverage: Extensive SQAA-specific tests cover entitled/not-entitled orgs, global/project scope interactions, and project key discovery paths
• MCP registration: .mcp.json is new; it registers the SonarQube MCP server for Copilot to use (implementation in mcp.ts)

---

• Generate Walkthrough
• Generate Diagram

🗣️ Give feedback

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
93.2% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonar-review-alpha]

LGTM! ✅

The previously flagged bug around uncaught errors in resolveSqaaProjectKey has been fixed — the function now wraps the API call in a try/catch and emits a warning on failure. The two acknowledged design decisions (global install writing SQAA-only to the project file, and the untested formatInstructionsLines "not installed" branch) remain as-is per prior agreement.

The rest of the PR is clean: the SQAA section logic, state tracking split, orphan-file warning, and the comprehensive new integration tests all look correct and follow the codebase's conventions.

🗣️ Give feedback