@provartesting/provardx-cli 1.5.0-dev.2 → 1.5.1

package/lib/services/qualityHub/client.js

@@ -0,0 +1,226 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+/* eslint-disable camelcase */
+import https from 'node:https';
+import { URL as NodeURL } from 'node:url';
+/**
+ * Map the raw API response to our internal validation result shape.
+ * Exported for unit testing; called by validateTestCaseViaApi once the stub is replaced.
+ *
+ * Mapping rules (from AWS memo 2026-04-10):
+ * raw.valid → is_valid
+ * raw.errors[].severity "critical" → issues[].severity "ERROR"
+ * raw.warnings[].severity * → issues[].severity "WARNING"
+ * raw.quality_metrics.quality_score → quality_score
+ * validity_score: 100 when valid, else max(0, 100 - errors.length * 20)
+ */
+export function normaliseApiResponse(raw) {
+    const issues = [
+        ...raw.errors.map((v) => ({
+            rule_id: v.rule_id,
+            severity: 'ERROR',
+            message: v.message,
+            applies_to: v.applies_to?.[0],
+            suggestion: v.recommendation,
+        })),
+        ...raw.warnings.map((v) => ({
+            rule_id: v.rule_id,
+            severity: 'WARNING',
+            message: v.message,
+            applies_to: v.applies_to?.[0],
+            suggestion: v.recommendation,
+        })),
+    ];
+    return {
+        is_valid: raw.valid,
+        validity_score: raw.valid ? 100 : Math.max(0, 100 - raw.errors.length * 20),
+        quality_score: raw.quality_metrics.quality_score,
+        issues,
+    };
+}
+/**
+ * Typed errors returned when the API call fails in a known way.
+ * The MCP tool maps these to appropriate fallback behaviour.
+ */
+export class QualityHubAuthError extends Error {
+    code = 'AUTH_ERROR';
+}
+export class QualityHubRateLimitError extends Error {
+    code = 'RATE_LIMITED';
+}
+/**
+ * POST /validate — submit XML to the Quality Hub validation API.
+ *
+ * Request:
+ * POST <baseUrl>/validate
+ * x-provar-key: pv_k_... (user auth — no x-api-key infra gate on this endpoint)
+ * Content-Type: application/json
+ * { "test_case_xml": "<full XML string>" }
+ *
+ * On failure the MCP tool catches and falls back to local validation
+ * (validation_source: "local_fallback"). No user-visible crash.
+ */
+export async function validateTestCaseViaApi(xml, apiKey, baseUrl) {
+    const body = JSON.stringify({ test_case_xml: xml });
+    const { status, responseBody } = await httpsRequest(`${baseUrl}/validate`, 'POST', { 'Content-Type': 'application/json', 'x-provar-key': apiKey }, body);
+    if (status === 401) {
+        throw new QualityHubAuthError('API key is invalid, expired, or revoked. Run `sf provar auth login` to get a new key.');
+    }
+    if (status === 429) {
+        throw new QualityHubRateLimitError('Quality Hub validation rate limit exceeded. Try again later.');
+    }
+    if (!isOk(status)) {
+        throw new Error(`Quality Hub validate failed (${status}): ${responseBody}`);
+    }
+    return normaliseApiResponse(JSON.parse(responseBody));
+}
+/**
+ * Returns the Quality Hub base URL to use for API calls.
+ * Defaults to the dev environment URL; override via PROVAR_QUALITY_HUB_URL for production.
+ * Update DEFAULT_QUALITY_HUB_URL when the production URL is confirmed.
+ */
+const DEFAULT_QUALITY_HUB_URL = 'https://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev';
+/**
+ * Self-service access request page for users who do not yet have a Provar MCP account.
+ * Public HTML — no API key or Cognito token required.
+ * Update when staging/prod stages are deployed.
+ */
+export const REQUEST_ACCESS_URL = `${DEFAULT_QUALITY_HUB_URL}/auth/request-access`;
+export function getQualityHubBaseUrl() {
+    return process.env.PROVAR_QUALITY_HUB_URL ?? DEFAULT_QUALITY_HUB_URL;
+}
+// ── Auth endpoint functions ───────────────────────────────────────────────────
+/**
+ * POST /auth/exchange — exchange a Cognito access token for a pv_k_ key.
+ * Called immediately after PKCE callback; Cognito tokens are discarded after this call.
+ */
+export async function exchangeTokenForKey(cognitoAccessToken, baseUrl) {
+    const body = JSON.stringify({ access_token: cognitoAccessToken });
+    const { status, responseBody } = await httpsRequest(`${baseUrl}/auth/exchange`, 'POST', { 'Content-Type': 'application/json' }, body);
+    if (status === 401)
+        throw new QualityHubAuthError(`Account not found or no active subscription.\nRequest access at: ${REQUEST_ACCESS_URL}`);
+    if (!isOk(status))
+        throw new Error(`Auth exchange failed (${status}): ${responseBody}`);
+    return JSON.parse(responseBody);
+}
+/**
+ * GET /auth/status — verify a stored pv_k_ key is still valid server-side.
+ * Best-effort: callers should catch and fall back to locally cached values on failure.
+ */
+export async function fetchKeyStatus(apiKey, baseUrl) {
+    const { status, responseBody } = await httpsRequest(`${baseUrl}/auth/status`, 'GET', {
+        'x-provar-key': apiKey,
+    });
+    if (!isOk(status))
+        throw new Error(`Auth status check failed (${status})`);
+    return JSON.parse(responseBody);
+}
+/**
+ * POST /auth/revoke — invalidate a pv_k_ key on the server.
+ * Best-effort: callers should catch, log a note, then delete the local file regardless.
+ */
+export async function revokeKey(apiKey, baseUrl) {
+    const { status, responseBody } = await httpsRequest(`${baseUrl}/auth/revoke`, 'POST', {
+        'x-provar-key': apiKey,
+        'Content-Length': '0',
+    });
+    if (!isOk(status))
+        throw new Error(`Key revocation failed (${status}): ${responseBody}`);
+}
+/**
+ * POST /auth/rotate — atomically replace the current pv_k_ key with a new one.
+ * The old key is invalidated immediately. Returns the same shape as /auth/exchange.
+ * On 401: key is invalid/expired — caller should direct user to sf provar auth login.
+ */
+export async function rotateKey(apiKey, baseUrl) {
+    const { status, responseBody } = await httpsRequest(`${baseUrl}/auth/rotate`, 'POST', {
+        'x-provar-key': apiKey,
+        'Content-Length': '0',
+    });
+    if (status === 401)
+        throw new QualityHubAuthError('API key is invalid or expired. Run `sf provar auth login` to get a new key.');
+    if (!isOk(status))
+        throw new Error(`Key rotation failed (${status}): ${responseBody}`);
+    return JSON.parse(responseBody);
+}
+// ── Corpus retrieval function ─────────────────────────────────────────────────
+/**
+ * POST /corpus/retrieve — fetch N similar Provar test examples from the Bedrock KB corpus.
+ * Used by provar.qualityhub.examples.retrieve as the few-shot grounding step before
+ * the client LLM synthesises a new test case.
+ *
+ * Throws QualityHubAuthError on 401, QualityHubRateLimitError on 429.
+ * All other non-2xx responses throw a generic Error with status + body.
+ */
+export async function retrieveCorpusExamples(query, apiKey, baseUrl, options = {}) {
+    const n = Math.min(Math.max(options.n ?? 5, 1), 10);
+    const body = JSON.stringify({
+        query,
+        n,
+        ...(options.app_filter !== undefined ? { app_filter: options.app_filter } : {}),
+        prefer_high_quality: options.prefer_high_quality ?? true,
+    });
+    const { status, responseBody } = await httpsRequest(`${baseUrl}/corpus/retrieve`, 'POST', { 'Content-Type': 'application/json', 'x-provar-key': apiKey }, body);
+    if (status === 401) {
+        throw new QualityHubAuthError('API key is invalid, expired, or revoked. Run `sf provar auth login` to get a new key.');
+    }
+    if (status === 429) {
+        throw new QualityHubRateLimitError('Quality Hub corpus retrieval rate limit exceeded. Try again later.');
+    }
+    if (!isOk(status)) {
+        throw new Error(`Corpus retrieval failed (${status}): ${responseBody}`);
+    }
+    return JSON.parse(responseBody);
+}
+// ── Internal HTTPS helper ─────────────────────────────────────────────────────
+function isOk(status) {
+    return status >= 200 && status < 300;
+}
+const REQUEST_TIMEOUT_MS = 30000;
+function httpsRequest(url, method, headers, body) {
+    return new Promise((resolve, reject) => {
+        const parsed = new NodeURL(url);
+        const opts = {
+            hostname: parsed.hostname,
+            port: parsed.port || undefined,
+            path: parsed.pathname + parsed.search,
+            method,
+            headers: {
+                ...headers,
+                ...(body ? { 'Content-Length': Buffer.byteLength(body).toString() } : {}),
+            },
+        };
+        const req = https.request(opts, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk.toString('utf-8');
+            });
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, responseBody: data }));
+        });
+        req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+            req.destroy(new Error(`Quality Hub API request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`));
+        });
+        req.on('error', reject);
+        if (body)
+            req.write(body);
+        req.end();
+    });
+}
+// ── Indirection object used by MCP tools and testable via sinon ───────────────
+/**
+ * MCP tools and auth commands call qualityHubClient.X() so tests can replace
+ * properties with stubs without ESM re-export issues.
+ */
+export const qualityHubClient = {
+    validateTestCaseViaApi,
+    exchangeTokenForKey,
+    fetchKeyStatus,
+    revokeKey,
+    rotateKey,
+    retrieveCorpusExamples,
+};
+//# sourceMappingURL=client.js.map

package/lib/services/qualityHub/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/services/qualityHub/client.ts"],"names":[],"mappings":"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"}

package/messages/sf.provar.auth.clear.md

@@ -0,0 +1,16 @@
+# summary
+
+Remove the stored Provar API key.
+
+# description
+
+Deletes the API key stored at ~/.provar/credentials.json. After clearing, the
+provar_testcase_validate MCP tool falls back to local validation (structural rules only,
+no Quality Hub quality scoring).
+
+The PROVAR_API_KEY environment variable is not affected by this command.
+
+# examples
+
+- Clear the stored API key:
+  <%= config.bin %> <%= command.id %>

package/messages/sf.provar.auth.login.md

@@ -0,0 +1,31 @@
+# summary
+
+Log in to Provar Quality Hub and store your API key.
+
+# 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 Cognito session tokens are held in memory only for the duration of the key
+exchange and are then discarded — only the pv*k* API key is written to disk.
+
+Run 'sf provar auth status' after login to confirm the key is configured correctly.
+
+Don't have an account? Request access at:
+https://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev/auth/request-access
+
+# flags.url.summary
+
+Override the Quality Hub API base URL (for testing against a non-production environment).
+
+# examples
+
+- Log in interactively (opens browser):
+
+  <%= config.bin %> <%= command.id %>
+
+- Log in against a staging environment:
+
+  <%= config.bin %> <%= command.id %> --url https://dev.api.example.com

package/messages/sf.provar.auth.rotate.md

@@ -0,0 +1,23 @@
+# summary
+
+Rotate your stored Provar Quality Hub API key.
+
+# description
+
+Exchanges your current pv*k* key for a new one in a single atomic operation.
+The old key is invalidated the moment the new key is issued — there is no window
+where both are valid.
+
+The new key is written to ~/.provar/credentials.json automatically.
+
+Use this command to rotate your key on a regular schedule (every ~90 days) without
+going through the browser login flow again.
+
+If the current key is already expired or revoked, rotation is not possible — run
+sf provar auth login instead to authenticate via browser and get a fresh key.
+
+# examples
+
+- Rotate the stored API key:
+
+  <%= config.bin %> <%= command.id %>

package/messages/sf.provar.auth.status.md

@@ -0,0 +1,16 @@
+# summary
+
+Show the current Provar API key configuration status.
+
+# description
+
+Reports where the active API key comes from (environment variable or stored file),
+shows the key prefix and when it was set, and states whether validation will use the
+Quality Hub API or local rules only. The full key is never printed.
+
+If no key is configured, guidance is shown for logging in or requesting access.
+
+# examples
+
+- Check auth status:
+  <%= config.bin %> <%= command.id %>

package/messages/sf.provar.mcp.start.md

@@ -1,71 +1,106 @@
 # summary
+
 Start a local MCP server for Provar tools over stdio transport.
 
 # description
+
 Launches a stateless MCP (Model Context Protocol) server that exposes Provar tools to
 AI assistants (Claude Desktop, Claude Code, Cursor) via stdio transport. All MCP
 JSON-RPC communication happens over stdout; all internal logging goes to stderr.
 
 Available tools:
 
-  Project & inspection:
-  - provar.project.inspect            — inspect project folder inventory
-  - provar.project.validate           — validate full project from disk: coverage, quality scores
-
-  Page Object:
-  - provar.pageobject.generate        — generate a Java Page Object skeleton
-  - provar.pageobject.validate        — validate Page Object quality and naming
-
-  Test Case:
-  - provar.testcase.generate          — generate an XML test case skeleton
-  - provar.testcase.validate          — validate test case XML (validity + best-practices scores)
-
-  Test Suite / Plan:
-  - provar.testsuite.validate         — validate test suite hierarchy
-  - provar.testplan.validate          — validate test plan metadata completeness
-  - provar.testplan.create-suite      — create a test suite under a plan
-  - provar.testplan.add-instance      — add a test instance to a plan
-  - provar.testplan.remove-instance   — remove a test instance from a plan
-
-  Properties files:
-  - provar.properties.read            — read a Provar properties file
-  - provar.properties.set             — set a key in a Provar properties file
-  - provar.properties.validate        — validate a properties file structure
-  - provar.properties.generate        — generate a properties file skeleton
-
-  Quality Hub (sf provar quality-hub wrappers):
-  - provar.qualityhub.connect         — connect to a Quality Hub org
-  - provar.qualityhub.display         — display connected org info
-  - provar.qualityhub.testrun         — trigger a Quality Hub test run
-  - provar.qualityhub.testrun.report  — poll test run status
-  - provar.qualityhub.testrun.abort   — abort a running test run
-  - provar.qualityhub.testcase.retrieve — retrieve test case results
-  - provar.qualityhub.defect.create   — create defects for failed test executions
-
-  Automation (sf provar automation wrappers):
-  - provar.automation.setup           — set up the Provar Automation runtime
-  - provar.automation.metadata.download — download Salesforce metadata
-  - provar.automation.compile         — compile Provar test assets
-  - provar.automation.testrun         — run Provar tests
-  - provar.automation.config.load     — load a Provar configuration
-
-  ANT build:
-  - provar.ant.generate               — generate an ANT build.xml
-  - provar.ant.validate               — validate an ANT build.xml
-
-  Test result analysis:
-  - provar.testrun.rca                — root cause analysis on a test result
-  - provar.testrun.report.locate      — locate a test result report
+Project & inspection:
+
+- provardx_ping — ping the MCP server (health check)
+- provar_project_inspect — inspect project folder inventory
+- provar_project_validate — validate full project from disk: coverage, quality scores
+- provar_connection_list — list connections and named environments from the project
+
+Page Object:
+
+- provar_pageobject_generate — generate a Java Page Object skeleton
+- provar_pageobject_validate — validate Page Object quality and naming
+
+Test Case:
+
+- provar_testcase_generate — generate an XML test case skeleton
+- provar_testcase_validate — validate test case XML (validity + best-practices scores)
+- provar_testcase_step_edit — atomically add or remove a single step in a test case
+
+Test Suite / Plan:
+
+- provar_testsuite_validate — validate test suite hierarchy
+- provar_testplan_validate — validate test plan metadata completeness
+- provar_testplan_create — create a new test plan
+- provar_testplan_create-suite — create a test suite under a plan
+- provar_testplan_add-instance — add a test instance to a plan
+- provar_testplan_remove-instance — remove a test instance from a plan
+
+Properties files:
+
+- provar_properties_read — read a Provar properties file
+- provar_properties_set — set a key in a Provar properties file
+- provar_properties_validate — validate a properties file structure
+- provar_properties_generate — generate a properties file skeleton
+
+Quality Hub (sf provar quality-hub wrappers):
+
+- provar_qualityhub_connect — connect to a Quality Hub org
+- provar_qualityhub_display — display connected org info
+- provar_qualityhub_testrun — trigger a Quality Hub test run
+- provar_qualityhub_testrun_report — poll test run status
+- provar_qualityhub_testrun_abort — abort a running test run
+- provar_qualityhub_testcase_retrieve — retrieve test case results
+- provar_qualityhub_defect_create — create defects for failed test executions
+- provar_qualityhub_examples_retrieve — retrieve corpus examples for test generation grounding
+
+Automation (sf provar automation wrappers):
+
+- provar_automation_setup — set up the Provar Automation runtime
+- provar_automation_metadata_download — download Salesforce metadata
+- provar_automation_compile — compile Provar test assets
+- provar_automation_testrun — run Provar tests
+- provar_automation_config_load — load a Provar configuration
+
+ANT build:
+
+- provar_ant_generate — generate an ANT build.xml
+- provar_ant_validate — validate an ANT build.xml
+
+Test result analysis:
+
+- provar_testrun_rca — root cause analysis on a test result
+- provar_testrun_report_locate — locate a test result report
+
+NitroX (Provar NitroX component tools):
+
+- provar_nitrox_discover — discover NitroX component metadata
+- provar_nitrox_generate — generate a NitroX component
+- provar_nitrox_patch — patch a NitroX component definition
+- provar_nitrox_read — read a NitroX component definition
+- provar_nitrox_validate — validate a NitroX component
 
 For full tool documentation see docs/mcp.md in this repository.
 
 # flags.allowed-paths.summary
+
 Allowed base directory paths for file operations. Defaults to current directory.
 
 # flags.auto-defects.summary
+
 When enabled, testrun.report suggestions will prompt defect creation on failures.
 
+# flags.auto-update.summary
+
+When enabled, automatically installs the latest version at startup and exits. The MCP client must reconnect to load the new version.
+
+# flags.no-update-check.summary
+
+Skip the update check at startup. Also controlled by the PROVAR_NO_UPDATE_CHECK environment variable.
+
 # examples
+
 - Start MCP server (accepts stdio connections from Claude Desktop / Cursor):
   <%= config.bin %> <%= command.id %>
 - Start with explicit allowed paths: