@provartesting/provardx-cli 1.5.0-beta.1 → 1.5.0-beta.10

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/oclif.manifest.json

@@ -1,5 +1,218 @@
 {
   "commands": {
+    "provar:auth:clear": {
+      "aliases": [],
+      "args": {},
+      "description": "Deletes the API key stored at ~/.provar/credentials.json. After clearing, the\nprovar.testcase.validate MCP tool falls back to local validation (structural rules only,\nno Quality Hub quality scoring).\n\nThe PROVAR_API_KEY environment variable is not affected by this command.",
+      "examples": [
+        "Clear the stored API key:\n<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "provar:auth:clear",
+      "pluginAlias": "@provartesting/provardx-cli",
+      "pluginName": "@provartesting/provardx-cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Remove the stored Provar API key.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "provar",
+        "auth",
+        "clear.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "provar:auth:clear",
+        "auth:provar:clear",
+        "auth:clear:provar",
+        "provar:clear:auth",
+        "clear:provar:auth",
+        "clear:auth:provar"
+      ]
+    },
+    "provar:auth:login": {
+      "aliases": [],
+      "args": {},
+      "description": "Opens a browser to the Provar login page. After you authenticate, your API key\nis stored at ~/.provar/credentials.json and used automatically by the Provar MCP\ntools and CI/CD integrations.\n\nThe Cognito session tokens are held in memory only for the duration of the key\nexchange and are then discarded — only the pv*k* API key is written to disk.\n\nRun 'sf provar auth status' after login to confirm the key is configured correctly.\n\nDon't have an account? Request access at:\nhttps://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev/auth/request-access",
+      "examples": [
+        "Log in interactively (opens browser):\n<%= config.bin %> <%= command.id %>",
+        "Log in against a staging environment:\n<%= config.bin %> <%= command.id %> --url https://dev.api.example.com"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "url": {
+          "name": "url",
+          "required": false,
+          "summary": "Override the Quality Hub API base URL (for testing against a non-production environment).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "provar:auth:login",
+      "pluginAlias": "@provartesting/provardx-cli",
+      "pluginName": "@provartesting/provardx-cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Log in to Provar Quality Hub and store your API key.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "provar",
+        "auth",
+        "login.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "provar:auth:login",
+        "auth:provar:login",
+        "auth:login:provar",
+        "provar:login:auth",
+        "login:provar:auth",
+        "login:auth:provar"
+      ]
+    },
+    "provar:auth:rotate": {
+      "aliases": [],
+      "args": {},
+      "description": "Exchanges your current pv*k* key for a new one in a single atomic operation.\nThe old key is invalidated the moment the new key is issued — there is no window\nwhere both are valid.\n\nThe new key is written to ~/.provar/credentials.json automatically.\n\nUse this command to rotate your key on a regular schedule (every ~90 days) without\ngoing through the browser login flow again.\n\nIf the current key is already expired or revoked, rotation is not possible — run\nsf provar auth login instead to authenticate via browser and get a fresh key.",
+      "examples": [
+        "Rotate the stored API key:\n<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "provar:auth:rotate",
+      "pluginAlias": "@provartesting/provardx-cli",
+      "pluginName": "@provartesting/provardx-cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Rotate your stored Provar Quality Hub API key.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "provar",
+        "auth",
+        "rotate.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "provar:auth:rotate",
+        "auth:provar:rotate",
+        "auth:rotate:provar",
+        "provar:rotate:auth",
+        "rotate:provar:auth",
+        "rotate:auth:provar"
+      ]
+    },
+    "provar:auth:status": {
+      "aliases": [],
+      "args": {},
+      "description": "Reports where the active API key comes from (environment variable or stored file),\nshows the key prefix and when it was set, and states whether validation will use the\nQuality Hub API or local rules only. The full key is never printed.\n\nIf no key is configured, guidance is shown for logging in or requesting access.",
+      "examples": [
+        "Check auth status:\n<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "provar:auth:status",
+      "pluginAlias": "@provartesting/provardx-cli",
+      "pluginName": "@provartesting/provardx-cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show the current Provar API key configuration status.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "provar",
+        "auth",
+        "status.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "provar:auth:status",
+        "auth:provar:status",
+        "auth:status:provar",
+        "provar:status:auth",
+        "status:provar:auth",
+        "status:auth:provar"
+      ]
+    },
     "provar:config:get": {
       "aliases": [],
       "args": {},
@@ -1811,5 +2024,5 @@
       ]
     }
   },
-  "version": "1.5.0-beta.1"
+  "version": "1.5.0-beta.10"
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@provartesting/provardx-cli",
   "description": "A plugin for the Salesforce CLI to orchestrate testing activities and report quality metrics to Provar Quality Hub",
-  "version": "1.5.0-beta.1",
+  "version": "1.5.0-beta.10",
+  "mcpName": "io.github.provartesting/provar",
   "license": "BSD-3-Clause",
   "plugins": [
     "@provartesting/provardx-plugins-automation",
@@ -35,7 +36,7 @@
     "wireit": "^0.14.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0 <25.0.0"
   },
   "files": [
     "/lib",
@@ -91,6 +92,9 @@
               }
             }
           },
+          "auth": {
+            "description": "Commands to manage Provar API key authentication."
+          },
           "automation": {
             "description": "Commands to interact with Provar Automation.",
             "subtopics": {
@@ -125,7 +129,7 @@
     "postpack": "shx rm -f oclif.manifest.json",
     "prepack": "sf-prepack",
     "test": "wireit",
-    "test:nuts": "nyc mocha  \"**/*generate.nut.ts\" \"**/*permission.nut.ts\" \"**/*load.nut.ts\" \"**/*validate.nut.ts\" \"**/*set.nut.ts\" \"**/*get.nut.ts\" --slow 4500 --timeout 600000 --reporter mochawesome",
+    "test:nuts": "nyc mocha  \"**/*generate.nut.ts\" \"**/*permission.nut.ts\" \"**/*load.nut.ts\" \"**/*validate.nut.ts\" \"**/*set.nut.ts\" \"**/*get.nut.ts\" \"**/*key.nut.ts\" \"**/*status.nut.ts\" \"**/*clear.nut.ts\" --slow 4500 --timeout 600000 --reporter mochawesome",
     "test:only": "wireit",
     "test:dev": "nyc mocha \"test/**/*.test.ts\"",
     "test:watch": "mocha \"test/**/*.test.ts\" --watch --watch-files \"src/**/*.ts\" --watch-files \"test/**/*.ts\"",
@@ -142,7 +146,7 @@
       ]
     },
     "compile": {
-      "command": "tsc -p . --pretty --incremental && shx mkdir -p lib/mcp/rules && shx cp src/mcp/rules/*.json lib/mcp/rules/",
+      "command": "tsc -p . --pretty --incremental && shx mkdir -p lib/mcp/rules && shx cp src/mcp/rules/*.json lib/mcp/rules/ && shx mkdir -p lib/mcp/docs && shx cp docs/PROVAR_TEST_STEP_REFERENCE.md lib/mcp/docs/",
       "files": [
         "src/**/*.ts",
         "src/mcp/rules/*.json",