CLI-499 skip sqaa during global integration

[sophio-japharidze-sonarsource]

No description provided.

[sonar-review-alpha]

Summary

What changed: This PR prevents SQAA (SonarQube Agentic Analysis) from being installed during global integration, even when the organization is entitled to it. SQAA is project-scoped functionality that must only be installed on a per-project basis.

Changes made:

• Added a guard in both Claude and Copilot integrations: !isGlobal && sqaaEntitled controls whether SQAA is actually installed
• Renamed sqaaEnabled → sqaaEntitled throughout to clarify the distinction between entitlement and actual installation
• Refactored health check/token repair logic into runHealthCheckAndRepair() helper function for clarity
• When users run a global integration and their org is SQAA-entitled, they now receive a warning with instructions to re-run per-project to enable SQAA
• Updated both integration and unit tests to verify SQAA is not installed during global setup, but the user is guided appropriately

Why it matters: Prevents a scope violation where project-level state/hooks were being installed globally, which would cause issues with per-project SQAA setup later.

What reviewers should know

Start here: Look at the core logic changes in both src/cli/commands/integrate/claude/index.ts (lines 85-92) and src/cli/commands/integrate/copilot/index.ts (lines 59-63) — these are the key guards that prevent SQAA installation during global mode.

Key decisions:

• SQAA entitlement is still checked (line 89 in claude) because users need to know they can enable it per-project; only installation is gated
• The new runHealthCheckAndRepair() function (lines 211-247 in claude) is a refactoring that also simplifies the main flow

What reviewers should verify:

1. The installSqaa variable correctly evaluates to false for global installs, preventing all SQAA artifacts (hooks, state, migrations) from being installed
2. Both integrations (Claude + Copilot) handle the guard identically for consistency
3. User-facing warnings (around line 266 in claude, line 107 in copilot) clearly direct users to re-run per-project
4. Test changes accurately reflect that global installs should produce no SQAA artifacts but do warn users
5. The refactored runHealthCheckAndRepair() maintains the original health check + optional repair logic without behavioral changes

---

• 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
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonar-review-alpha]

Clean, well-scoped fix. The installSqaa = !isGlobal && sqaaEntitled guard is applied consistently across all three call sites (runMigrations, installSqaaHook, updateStateAfterConfiguration), and the runHealthCheckAndRepair refactor faithfully preserves the original repair logic. One logic duplication worth tidying up.

🗣️ Give feedback

[sonar-review-alpha]

Logic duplication: This warning message is functionally identical to the one in src/cli/commands/integrate/copilot/index.ts:108-110 — same first sentence, same structure, only the command name differs. Any future wording change (e.g. renaming "SonarQube Agentic Analysis" or adjusting the hint syntax) requires two edits in non-obvious locations.

Extract a shared helper parameterised on the integration name (e.g. in integrate/_common/):

export function warnSqaaSkippedOnGlobalInstall(integration: 'claude' | 'copilot'): void {
  warn(
    `SonarQube Agentic Analysis is project-scoped and is not enabled by this global install. ` +
    `Run \`sonar integrate ${integration} --project <key>\` from a project directory to enable it for that project.`,
  );
}

Then call it from both reportHookInstallationOutcome and reportInstallationOutcome.