@codyswann/lisa 2.296.1 → 2.297.0

package/plugins/src/base/skills/lisa-setup-sonar/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: lisa-setup-sonar
+description: "Configure the official SonarQube plugin + MCP as Lisa's single Sonar substrate across every supported coding agent. Installs/updates the SonarQube CLI, authenticates (browser login on a dev machine, or SONARQUBE_TOKEN headless), selects the Test Manager target, runs `sonar integrate <agent>` for each supported agent (Claude, Codex, Cursor, Copilot, Antigravity) and wires the MCP for OpenCode, then writes only non-secret policy to .lisa.config.json. Separate from the CI SonarCloud scan gate, which is unchanged."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "AskUserQuestion", "Skill"]
+---
+
+# Set up SonarQube (official plugin + MCP)
+
+This is an explicit exterior setup gate. Run it **outside** any active Build, QA,
+Monitor, or Verify factory — authentication and MCP wiring must be complete before
+unattended factories run. It replaces Lisa's former hand-rolled SonarCloud REST
+access with the vendor's official token-authed MCP, which is Lisa's single Sonar
+substrate on both developer machines and headless cloud routines.
+
+This does **not** touch the CI SonarCloud SAST job in `quality.yml` or its
+`SONAR_TOKEN` secret — that enforcement gate is separate and stays as-is.
+
+## Supported agents
+
+Wire only Lisa's supported agents: **Claude Code, Codex, Cursor, GitHub Copilot,
+Antigravity (agy)** via `sonar integrate <agent>`, and **OpenCode** via its MCP
+config. **Never** wire Kiro or Gemini CLI even though the vendor supports them —
+they are not Lisa-supported agents.
+
+## 1. Install or update the SonarQube CLI
+
+Check `sonar` on PATH (`command -v sonar`). If present, update it (`sonar
+self-update`, or the package manager that owns it); if absent, install it and ask
+for confirmation before running the install:
+
+```bash
+# macOS/Linux (script) — default, works everywhere
+curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash
+# or Homebrew: brew install --cask sonarqube-cli
+# or mise:     mise use -g aqua:SonarSource/sonarqube-cli
+```
+
+A container runtime (Docker/Podman/Nerdctl) must be installed and running — the
+MCP runs as a container via `sonar run mcp`. Probe with `docker ps` (falling back
+to `podman ps` / `nerdctl ps`). If none succeed, tell the operator to start it and
+note the agent session must restart afterward for the MCP tools to load.
+
+## 2. Authenticate — token for factories, login for dev machines
+
+The MCP authenticates from environment variables — this is the headless path and
+the one factories use. **Never** write credentials to `.lisa.config.json` or
+`.lisa.config.local.json`; provide them as environment variables / CI secrets:
+
+- `SONARQUBE_TOKEN` — required.
+- `SONARQUBE_ORG` — for SonarQube Cloud.
+- `SONARQUBE_URL` — for a self-hosted SonarQube Server.
+
+On an interactive developer machine you may instead run `sonar auth login`
+(browser flow; token stored in the OS keychain). Do **not** use the keychain flow
+for headless/cloud-routine environments — provision the env token there instead
+(see `/lisa:generate-claude-remote-build-script`, which now installs the CLI,
+pre-pulls the MCP image, and sets `SONARQUBE_TOKEN`). Verify with `sonar auth
+status`; record the identity label only, never token material.
+
+## 3. Select the Test Manager target
+
+Use `sonar config project` (and optional `sonar config folder`), then `sonar
+config show`. Capture the non-secret project/organization identifiers.
+
+## 4. Integrate per supported agent
+
+Confirm the target scope (single-choice: current project / global), then for each
+supported agent detected on PATH run its non-interactive integrate:
+
+```bash
+sonar integrate claude       --non-interactive
+sonar integrate codex        --non-interactive
+sonar integrate cursor       --non-interactive
+sonar integrate copilot      --non-interactive
+sonar integrate antigravity  --non-interactive
+```
+
+For **OpenCode** (no vendor integrate path), wire the MCP through OpenCode's own
+MCP config so it launches `sonar run mcp`, authenticated from the same env token.
+
+Skip any agent whose CLI is not installed; never wire Kiro or Gemini.
+
+## 5. Write non-secret policy config
+
+Merge only non-secret identifiers into committed `.lisa.config.json`, preserving
+every unrelated key (never credentials):
+
+```json
+{
+  "verification": {
+    "sonar": {
+      "enabled": true,
+      "edition": "cloud",
+      "organization": "<org-key>",
+      "projectKey": "<project-key>"
+    }
+  }
+}
+```
+
+Use `"edition": "server"` with a `"serverUrl"` for a self-hosted Server.
+
+## 6. Prove readiness
+
+Run the `lisa-sonarcloud-access` probe (an `mcp__sonarqube__*` project search) and
+confirm a `mcp__sonarqube__*` tool answers. Then run `lisa doctor` and confirm the
+Sonar provider check is green. If the MCP tools do not appear, verify the container
+runtime is running and restart the agent session.

package/plugins/src/base/skills/lisa-sonarcloud-access/SKILL.md

@@ -1,71 +1,76 @@
 ---
 name: lisa-sonarcloud-access
-description: "Vendor-neutral access layer for SonarCloud/SonarQube Cloud. Sonar triage skills MUST delegate through this skill rather than calling Sonar MCP tools or REST directly. Resolves Sonar MCP first when available, then falls back to SONAR_TOKEN + SonarCloud Web API."
+description: "Vendor-neutral access layer for SonarQube Cloud/Server. Sonar triage skills MUST delegate through this skill rather than calling the SonarQube MCP tools directly. Single substrate: the official SonarQube MCP server (mcp__sonarqube__*), authenticated headlessly from SONARQUBE_TOKEN (+ SONARQUBE_ORG for Cloud, SONARQUBE_URL for Server)."
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
 # SonarCloud Access: $ARGUMENTS
 
-Single chokepoint for SonarCloud operations. Caller skills MUST NOT call
-`mcp__sonarqube__*` tools directly or curl `https://sonarcloud.io/api/`
-themselves.
+Single chokepoint for Sonar quality and security data. Caller skills MUST NOT
+invoke `mcp__sonarqube__*` tools directly; they ask for data by operation name and
+this skill owns the tool selection.
 
-## Invocation Contract
+## Substrate
 
-```text
-operation: gate-status project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
-operation: issues project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>] [types:<csv>] [severities:<csv>]
-operation: hotspots project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
-operation: rule-detail key:<RULE_KEY>
-operation: source-snippet component:<COMPONENT_KEY> from:<N> to:<N>
-```
+There is exactly one substrate: the **official SonarQube MCP server**, provided by
+the `sonarqube` plugin and launched by the `sonar` CLI (`sonar run mcp`). It
+authenticates headlessly from environment variables — no browser, no OS keychain —
+so it is the same substrate on a developer machine and in a headless cloud routine:
 
-Return parsed JSON in a `<result>` block.
+- `SONARQUBE_TOKEN` — required (Sonar user/analysis token).
+- `SONARQUBE_ORG` — required for SonarQube Cloud.
+- `SONARQUBE_URL` — required for a self-hosted SonarQube Server.
 
-## Substrate Selection
+Wiring is performed once by `/lisa:setup:sonar` (which drives `sonar integrate
+<agent>`); this access layer assumes the MCP is already wired. This is distinct
+from the CI `SONAR_TOKEN` secret that authenticates the SonarCloud scan job in
+`quality.yml` — that gate is separate and unchanged.
 
-Probe in order:
+## Probe (tool-access-gate)
 
-1. Sonar MCP, if available and authenticated.
-2. `SONAR_TOKEN` against the SonarCloud Web API.
+Prove access with a cheap read-only MCP call before relying on it — the `sonar` CLI
+being on PATH is not access. Probe by searching projects (the `projects` toolset is
+always enabled):
 
-SonarCloud documents bearer-token authentication for the Web API. Use:
+- If a `mcp__sonarqube__*` project-search tool returns, access is proven.
+- If no `mcp__sonarqube__*` tool is present, or the call fails authentication, fail
+  loudly and do not improvise a substitute:
 
-```bash
-sonar_api() {
-  local path="$1"
-  [ -n "$SONAR_TOKEN" ] || {
-    echo "Error: SONAR_TOKEN is not set." >&2
-    return 1
-  }
-  curl -sS "https://sonarcloud.io/api${path}" \
-    -H "Authorization: Bearer $SONAR_TOKEN"
-}
+```text
+Error: no SonarQube access. Run /lisa:setup:sonar (or `sonar integrate <agent>`), and set SONARQUBE_TOKEN (+ SONARQUBE_ORG for Cloud / SONARQUBE_URL for Server).
 ```
 
-If a host still requires the legacy token-as-basic-auth form, make that an
-explicit adapter branch in this skill; consumers do not choose auth style.
+There is no hand-rolled REST fallback: the official MCP is headless-capable via the
+token env vars, so it is the only sanctioned substrate. A missing MCP is a
+tool-access-gate failure to surface, not a reason to curl the Web API.
 
-If neither tier works, fail with:
-
-```text
-Error: no SonarCloud access substrate available. Authenticate the Sonar MCP or set SONAR_TOKEN.
-```
+## Operation → toolset map
 
-## REST Dispatch
+Consumers pass a coarse, vendor-native operation; resolve it with the matching
+`mcp__sonarqube__*` tool from the named toolset and return parsed JSON in a
+`<result>` block.
 
-| Operation | REST path |
+| Operation | SonarQube MCP toolset |
 |---|---|
-| `gate-status` | `/qualitygates/project_status?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
-| `issues` | `/issues/search?componentKeys=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]...` |
-| `hotspots` | `/hotspots/search?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
-| `rule-detail` | `/rules/show?key=<RULE_KEY>` |
-| `source-snippet` | `/sources/lines?key=<COMPONENT_KEY>&from=<N>&to=<N>` |
+| `gate-status` | `quality-gates` |
+| `issues` | `issues` |
+| `hotspots` | `security-hotspots` |
+| `rule-detail` | `rules` |
+| `source-snippet` | `cag` (context augmentation) / component source |
+| `coverage` | `coverage` |
+| `duplication` | `duplications` |
+| `dependency-risks` | `dependency-risks` |
+| `projects` | `projects` |
+
+Pass the project key through the tool's `projectKey` argument (or rely on a
+server-configured `SONARQUBE_PROJECT_KEY`); pass `branch` / `pullRequest` where the
+tool accepts them.
 
 ## Invariants
 
-- Fallback is gated on `SONAR_TOKEN`.
-- SonarCloud host access requires `sonarcloud.io` in any custom remote network
-  allowlist.
-- Consumers ask for analysis data by operation name; this skill owns the Web API
-  path shape.
+- The official SonarQube MCP is the only substrate; there is no REST fallback.
+- Auth is env-var only (`SONARQUBE_TOKEN` [+ `SONARQUBE_ORG` | `SONARQUBE_URL`]);
+  never the interactive `sonar auth login` keychain flow inside a factory.
+- Sonar host access requires the host (`sonarcloud.io`, `sonarqube.us`, or the
+  Server URL) in any custom remote-network allowlist.
+- Consumers ask for data by operation name; this skill owns tool selection.