Feature/auth and quality hub api

messages/sf.provar.auth.clear.md

@@ -0,0 +1,13 @@
+# 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 %>

messages/sf.provar.auth.set-key.md

@@ -0,0 +1,19 @@
+# summary
+Store a Provar API key for Quality Hub validation.
+
+# description
+Saves a Provar API key to ~/.provar/credentials.json so the MCP server can call the
+Quality Hub validation API automatically. Keys must start with "pv_k_". The full key
+is never echoed — only the prefix is shown after storing.
+
+To get a key, visit https://success.provartesting.com.
+
+For CI/CD environments, set the PROVAR_API_KEY environment variable instead of using
+this command.
+
+# flags.key.summary
+Provar API key to store. Must start with "pv_k_". The value is stored on disk; the full key is never printed back.
+
+# examples
+- Store an API key:
+  <%= config.bin %> <%= command.id %> --key pv_k_yourkeyhere

messages/sf.provar.auth.status.md

@@ -0,0 +1,11 @@
+# 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.
+
+# examples
+- Check auth status:
+  <%= config.bin %> <%= command.id %>

package.json

@@ -91,6 +91,9 @@
               }
             }
           },
+          "auth": {
+            "description": "Commands to manage Provar API key authentication."
+          },
           "automation": {
             "description": "Commands to interact with Provar Automation.",
             "subtopics": {

src/commands/provar/auth/clear.ts

@@ -0,0 +1,27 @@
+/*
+ * 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
+ */
+
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { Messages } from '@provartesting/provardx-plugins-utils';
+import { clearCredentials } from '../../../services/auth/credentials.js';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@provartesting/provardx-cli', 'sf.provar.auth.clear');
+
+export default class SfProvarAuthClear extends SfCommand<void> {
+  public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
+  public static readonly examples = messages.getMessages('examples');
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  public async run(): Promise<void> {
+    clearCredentials();
+    this.log('API key cleared.');
+    this.log('  Next validation will use local rules only (structural checks, no quality scoring).');
+    this.log('  To reconfigure, run: sf provar auth set-key --key <your-key>');
+  }
+}

src/commands/provar/auth/set-key.ts

@@ -0,0 +1,44 @@
+/*
+ * 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
+ */
+
+import { Flags, SfCommand } from '@salesforce/sf-plugins-core';
+import { Messages } from '@provartesting/provardx-plugins-utils';
+import { writeCredentials } from '../../../services/auth/credentials.js';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@provartesting/provardx-cli', 'sf.provar.auth.set-key');
+
+export default class SfProvarAuthSetKey extends SfCommand<void> {
+  public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
+  public static readonly examples = messages.getMessages('examples');
+
+  public static readonly flags = {
+    key: Flags.string({
+      summary: messages.getMessage('flags.key.summary'),
+      required: true,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(SfProvarAuthSetKey);
+    const key = flags.key;
+
+    if (!key.startsWith('pv_k_')) {
+      this.error(
+        'Invalid API key format. Keys must start with "pv_k_". Get your key from https://success.provartesting.com.',
+        { exit: 1 }
+      );
+    }
+
+    const prefix = key.substring(0, 12);
+    writeCredentials(key, prefix, 'manual');
+
+    this.log(`API key stored (prefix: ${prefix}).`);
+    this.log("Run 'sf provar auth status' to verify.");
+  }
+}

src/commands/provar/auth/status.ts

@@ -0,0 +1,57 @@
+/*
+ * 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
+ */
+
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { Messages } from '@provartesting/provardx-plugins-utils';
+import { readStoredCredentials } from '../../../services/auth/credentials.js';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@provartesting/provardx-cli', 'sf.provar.auth.status');
+
+export default class SfProvarAuthStatus extends SfCommand<void> {
+  public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
+  public static readonly examples = messages.getMessages('examples');
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  public async run(): Promise<void> {
+    const envKey = process.env.PROVAR_API_KEY?.trim();
+
+    if (envKey) {
+      this.log('API key configured');
+      this.log('  Source:   environment variable (PROVAR_API_KEY)');
+      this.log(`  Prefix:   ${envKey.substring(0, 12)}`);
+      this.log('');
+      this.log('  Validation mode: Quality Hub API');
+      return;
+    }
+
+    const stored = readStoredCredentials();
+    if (stored) {
+      this.log('API key configured');
+      this.log('  Source:   ~/.provar/credentials.json');
+      this.log(`  Prefix:   ${stored.prefix}`);
+      this.log(`  Set at:   ${stored.set_at}`);
+      if (stored.username) this.log(`  Account:  ${stored.username}`);
+      if (stored.tier) this.log(`  Tier:     ${stored.tier}`);
+      if (stored.expires_at) this.log(`  Expires:  ${stored.expires_at}`);
+      this.log('');
+      this.log('  Validation mode: Quality Hub API');
+      return;
+    }
+
+    this.log('No API key configured.');
+    this.log('');
+    this.log('To enable Quality Hub validation (170 rules):');
+    this.log('  1. Get your API key from https://success.provartesting.com');
+    this.log('  2. Run: sf provar auth set-key --key <your-key>');
+    this.log('');
+    this.log('For CI/CD: set the PROVAR_API_KEY environment variable.');
+    this.log('');
+    this.log('Validation mode: local only (structural rules, no quality scoring)');
+  }
+}