Feature/auth and quality hub api

.github/workflows/CI_Execution.yml

@@ -124,7 +124,9 @@ jobs:
           sf plugins link .
           yarn run test:nuts
       - name: Archive NUTS results
+        if: always()
         uses: actions/upload-artifact@v4
         with:
           name: nuts-report-${{ matrix.os }}
           path: mochawesome-report
+          if-no-files-found: warn

README.md

@@ -30,7 +30,9 @@ $ sf plugins uninstall @provartesting/provardx-cli
 
 # MCP Server (AI-Assisted Quality)
 
-The Provar DX CLI includes a built-in **Model Context Protocol (MCP) server** that connects AI assistants (Claude Desktop, Claude Code, Cursor) directly to your Provar project. Once connected, an AI agent can inspect your project structure, generate Page Objects and test cases, validate every level of the test hierarchy with quality scores that match the Provar Quality Hub API, and work with NitroX (Hybrid Model) component page objects for LWC, Screen Flow, Industry Components, Experience Cloud, and HTML5.
+The Provar DX CLI includes a built-in **Model Context Protocol (MCP) server** that connects AI assistants (Claude Desktop, Claude Code, Cursor) directly to your Provar project. Once connected, an AI agent can inspect your project structure, generate Page Objects and test cases, validate every level of the test hierarchy with quality scores, and work with NitroX (Hybrid Model) component page objects for LWC, Screen Flow, Industry Components, Experience Cloud, and HTML5.
+
+Validation runs in two modes: **local only** (structural rules, no key required) or **Quality Hub API** (170+ rules, quality scoring — requires a `pv_k_` API key). Run `sf provar auth login` to authenticate and unlock full validation.
 
 ```sh
 sf provar mcp start --allowed-paths /path/to/your/provar/project
@@ -57,6 +59,9 @@ When `NODE_ENV=test` the validation step is skipped entirely. This is intended o
 
 # Commands
 
+- [`sf provar auth login`](#sf-provar-auth-login)
+- [`sf provar auth status`](#sf-provar-auth-status)
+- [`sf provar auth clear`](#sf-provar-auth-clear)
 - [`sf provar mcp start`](#sf-provar-mcp-start)
 - [`sf provar config get`](#sf-provar-config-get)
 - [`sf provar config set`](#sf-provar-config-set)
@@ -84,6 +89,74 @@ When `NODE_ENV=test` the validation step is skipped entirely. This is intended o
 - [`sf provar manager test run report`](#sf-provar-manager-test-run-report) _(deprecated — use `sf provar quality-hub test run report`)_
 - [`sf provar manager test run abort`](#sf-provar-manager-test-run-abort) _(deprecated — use `sf provar quality-hub test run abort`)_
 
+## `sf provar auth login`
+
+Log in to Provar Quality Hub and store your API key.
+
+```
+USAGE
+  $ sf provar auth login [--url <value>]
+
+FLAGS
+  --url=<value>  Override the Quality Hub API base URL (for non-production environments).
+
+DESCRIPTION
+  Opens a browser to the Provar login page. After you authenticate, your API key is
+  stored at ~/.provar/credentials.json and used automatically by the Provar MCP tools
+  and CI/CD integrations. The key is valid for approximately 90 days.
+
+  For CI/CD pipelines (GitHub Actions, Jenkins, etc.) where a browser cannot open:
+  run sf provar auth login once on your local machine, copy the api_key value from
+  ~/.provar/credentials.json, and store it as the PROVAR_API_KEY environment variable
+  or secret in your pipeline. Rotate the secret every ~90 days when the key expires.
+
+EXAMPLES
+  Log in interactively:
+
+    $ sf provar auth login
+
+  Log in against a staging environment:
+
+    $ sf provar auth login --url https://dev.api.example.com
+```
+
+## `sf provar auth status`
+
+Show the current API key configuration and validate it against Quality Hub.
+
+```
+USAGE
+  $ sf provar auth status
+
+DESCRIPTION
+  Reports whether an API key is configured, where it came from (environment variable
+  or credentials file), and performs a live check against the Quality Hub API to
+  confirm the key is still valid.
+
+EXAMPLES
+  Check auth status:
+
+    $ sf provar auth status
+```
+
+## `sf provar auth clear`
+
+Remove the stored API key.
+
+```
+USAGE
+  $ sf provar auth clear
+
+DESCRIPTION
+  Deletes ~/.provar/credentials.json and revokes the key server-side. After clearing,
+  the MCP tools fall back to local validation mode. Has no effect if no key is stored.
+
+EXAMPLES
+  Remove the stored key:
+
+    $ sf provar auth clear
+```
+
 ## `sf provar mcp start`
 
 Start a local MCP server for Provar tools over stdio transport.

docs/mcp-pilot-guide.md

@@ -165,6 +165,9 @@ Prompt your AI assistant:
 - `validity_score` and `quality_score` both returned (0–100)
 - Specific rule violations called out (e.g. TC_010 missing test case ID, TC_001 missing XML declaration)
 - Best-practices suggestions (e.g. hardcoded credentials, missing step descriptions)
+- `validation_source: "local"` if no API key is configured, `"quality_hub"` if authenticated
+
+> **Tip:** Run `sf provar auth login` before this scenario to unlock Quality Hub API validation (170+ rules). Without a key the tool still returns useful results using local rules only.
 
 ---
 
@@ -226,6 +229,24 @@ Pre-requisite: `sf org login web -a MyQHOrg` then `sf provar quality-hub connect
 
 ---
 
+### Scenario 8: Quality Hub API Validation
+
+**Goal:** Confirm that `provar.testcase.validate` upgrades from local rules to the full Quality Hub API ruleset when an API key is present.
+
+**Setup:** Run `sf provar auth login` and complete the browser login, then confirm with `sf provar auth status`.
+
+> "Validate the test case at `/path/to/project/tests/LoginTest.testcase` and tell me what validation_source was used."
+
+**What to look for:**
+
+- `validation_source: "quality_hub"` in the response — confirms the API path is active
+- `quality_score` reflecting the full 170+ rule evaluation
+- If the API is unreachable, `validation_source: "local_fallback"` and a `validation_warning` field explaining why
+
+**To reset and test the fallback:** run `sf provar auth clear`, repeat the prompt, and verify `validation_source` reverts to `"local"`.
+
+---
+
 ### Scenario 7: NitroX (Hybrid Model) Page Object Generation
 
 **Goal:** Have the AI discover, understand, and generate NitroX component page objects.
@@ -323,7 +344,9 @@ The MCP server uses **stdio transport** exclusively. Communication travels over
 
 ### Credential handling
 
-The Quality Hub and Automation tools invoke `sf` subprocesses. Salesforce org credentials are managed entirely by the Salesforce CLI and stored in its own credential store. The Provar MCP server never reads, parses, or transmits those credentials.
+**Salesforce org credentials** — the Quality Hub and Automation tools invoke `sf` subprocesses. Salesforce org credentials are managed entirely by the Salesforce CLI and stored in its own credential store (`~/.sf/`). The Provar MCP server never reads, parses, or transmits those credentials.
+
+**Provar API key** — the `provar.testcase.validate` tool optionally reads a `pv_k_` API key to enable Quality Hub API validation. The key is stored at `~/.provar/credentials.json` (written by `sf provar auth login`) or read from the `PROVAR_API_KEY` environment variable. The key is sent to the Provar Quality Hub API only when a validation request is made — it is never logged or written anywhere other than `~/.provar/credentials.json`.
 
 ### Path policy enforcement
 

docs/mcp.md

@@ -140,6 +140,58 @@ If the license check fails, the server exits with a clear error message explaini
 
 ---
 
+## Authentication — Quality Hub API
+
+The `provar.testcase.validate` tool can run in two modes depending on whether an API key is configured.
+
+| Mode | When | What you get |
+|---|---|---|
+| **Quality Hub API** | API key configured | 170+ rules, quality score, tier-specific thresholds |
+| **Local only** | No key | Structural/schema rules only |
+
+The `validation_source` field in every `provar.testcase.validate` response tells you which mode fired:
+
+| Value | Meaning |
+|---|---|
+| `quality_hub` | Full API validation — key is valid and the API responded |
+| `local` | No key configured — local rules only |
+| `local_fallback` | Key is configured but the API was unreachable or returned an error — local rules used as fallback |
+
+When `validation_source` is `local_fallback`, a `validation_warning` field is also returned explaining why.
+
+### Configuring an API key
+
+**Interactive login (recommended):**
+```sh
+sf provar auth login
+```
+Opens a browser to the Provar login page. After you authenticate, the key is stored automatically at `~/.provar/credentials.json`.
+
+**Check current status:**
+```sh
+sf provar auth status
+```
+
+**CI/CD — environment variable:**
+```sh
+export PROVAR_API_KEY=pv_k_your_key_here
+```
+The env var takes priority over any stored key. Keys must start with `pv_k_` — any other value is ignored.
+
+**Remove stored key:**
+```sh
+sf provar auth clear
+```
+
+### Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `PROVAR_API_KEY` | API key for Quality Hub validation | None — falls back to `~/.provar/credentials.json` |
+| `PROVAR_QUALITY_HUB_URL` | Override the Quality Hub API base URL | Production URL |
+
+---
+
 ## Path security
 
 All file-system operations (read, write, generate) are restricted to the paths supplied via `--allowed-paths`. Any attempt to access a path outside those roots is rejected with a `PATH_NOT_ALLOWED` error. Path traversal sequences (`../`) are blocked with a `PATH_TRAVERSAL` error.
@@ -306,6 +358,8 @@ Validates an XML test case for schema correctness (validity score) and best prac
 | `issues`                         | array          | Schema issues with `rule_id`, `severity`, `message`                       |
 | `best_practices_violations`      | array          | Best-practices violations with `rule_id`, `severity`, `weight`, `message` |
 | `best_practices_rules_evaluated` | integer        | How many best-practices rules were checked                                |
+| `validation_source`              | string         | `quality_hub`, `local`, or `local_fallback` — see Authentication section  |
+| `validation_warning`             | string         | Present when `validation_source` is `local_fallback` — explains why       |
 
 **Key schema rules:** TC_001 (missing XML declaration), TC_002 (malformed XML), TC_003 (wrong root element), TC_010/011/012 (missing/invalid id/guid), TC_031 (invalid apiCall guid), TC_034/035 (non-integer testItemId).