@provartesting/provardx-cli 1.4.6 → 1.5.0-dev

package/lib/mcp/licensing/licenseValidator.js

@@ -0,0 +1,103 @@
+/*
+ * 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 { log } from '../logging/logger.js';
+import { hashKey, readCacheEntry, writeCacheEntry, isCacheEntryFresh, isCacheEntryWithinGrace, } from './licenseCache.js';
+import { findActivatedIdeLicense } from './ideDetection.js';
+import { LicenseError } from './licenseError.js';
+/**
+ * Stable cache key used for IDE-detection results.
+ * There is no user-supplied key in this flow, so we use a fixed sentinel.
+ */
+const IDE_CACHE_KEY = '__ide_detection__';
+/**
+ * Validate the Provar license before starting the MCP server.
+ *
+ * Requires Provar Automation IDE to be installed with an activated licence.
+ * We trust the IDE's own licenseStatus field — if it says "Activated" we
+ * accept it. The IDE is responsible for setting licenseStatus to "Expired"
+ * or "Invalid" when a licence lapses; we do not re-check timing ourselves.
+ *
+ * The result is cached so repeated starts within 2 hours skip the IDE file
+ * read entirely. The 48-hour grace window lets the MCP server keep running
+ * when the IDE files become temporarily inaccessible (e.g. network share,
+ * permission change) after a successful read.
+ *
+ * Validation flow:
+ * 1. MCP cache fresh (< 2h) → serve from cache, skip IDE read
+ * 2. Scan ~/Provar/.licenses/*.properties for an Activated licence
+ * 3. Found → write cache, accept (offlineGrace=false)
+ * 4. Not found but MCP cache within 48h grace → serve, offlineGrace=true
+ * 5. Not found, no usable cache → throw LICENSE_NOT_FOUND
+ *
+ * When NODE_ENV=test this function returns immediately so unit tests never
+ * touch the filesystem.
+ */
+export function validateLicense() {
+    // Skip validation in test environment
+    if (process.env.NODE_ENV === 'test') {
+        return Promise.resolve({ valid: true, licenseType: 'Whitelisted', fromCache: false, offlineGrace: false });
+    }
+    // Dev whitelist — PROVAR_DEV_WHITELIST_KEYS is a comma-separated list of bypass sentinels.
+    // Any non-empty entry (after trimming) bypasses all license checks, enabling headless CI/dev
+    // environments to run without an IDE or an API call.
+    const whitelistKeys = (process.env['PROVAR_DEV_WHITELIST_KEYS'] ?? '')
+        .split(',')
+        .map((k) => k.trim())
+        .filter(Boolean);
+    if (whitelistKeys.length > 0) {
+        log('info', 'licenseValidator: PROVAR_DEV_WHITELIST_KEYS active — bypassing license check');
+        return Promise.resolve({ valid: true, licenseType: 'Whitelisted', fromCache: false, offlineGrace: false });
+    }
+    try {
+        return Promise.resolve(validateViaIdeDetection());
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+}
+// ── IDE auto-detection ───────────────────────────────────────────────────────
+function validateViaIdeDetection() {
+    const keyHash = hashKey(IDE_CACHE_KEY);
+    const cached = readCacheEntry(keyHash);
+    // 1. Serve from MCP cache when fresh (< 2h) — skip IDE file read entirely
+    if (cached && isCacheEntryFresh(cached)) {
+        log('info', 'licenseValidator: IDE detection — fresh cache hit', { licenseType: cached.licenseType });
+        return { valid: true, licenseType: cached.licenseType, fromCache: true, offlineGrace: false };
+    }
+    // 2. Read the IDE .properties files
+    const ideState = findActivatedIdeLicense();
+    if (!ideState) {
+        // IDE not readable — fall back to grace cache if available
+        if (cached && isCacheEntryWithinGrace(cached)) {
+            const ageHours = Math.round((Date.now() - cached.checkedAt) / (60 * 60 * 1000));
+            log('warn', 'licenseValidator: IDE license not found, serving from offline grace cache', { ageHours });
+            return { valid: true, licenseType: cached.licenseType, fromCache: true, offlineGrace: true };
+        }
+        throw new LicenseError('LICENSE_NOT_FOUND', 'No activated Provar license found on this machine.\n' +
+            'Activate a license in Provar Automation IDE to use the MCP server.\n' +
+            'Licenses are read from: ~/Provar/.licenses/');
+    }
+    // 3. Valid — write to MCP cache so next start within 2h skips this read
+    const entry = {
+        keyHash,
+        valid: true,
+        licenseType: ideState.licenseType,
+        checkedAt: Date.now(),
+    };
+    writeCacheEntry(entry);
+    log('info', 'licenseValidator: IDE licence validated and cached', {
+        name: ideState.name,
+        licenseType: ideState.licenseType,
+    });
+    return {
+        valid: true,
+        licenseType: ideState.licenseType,
+        fromCache: false,
+        offlineGrace: false,
+    };
+}
+//# sourceMappingURL=licenseValidator.js.map

package/lib/mcp/licensing/licenseValidator.js.map

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

package/lib/mcp/logging/logger.d.ts

@@ -0,0 +1,7 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Write a structured log entry to stderr.
+ * stdout is reserved exclusively for MCP JSON-RPC messages.
+ * IMPORTANT: data MUST NOT contain locator values, file content, or user PII.
+ */
+export declare function log(level: LogLevel, message: string, data?: Record<string, unknown>): void;

package/lib/mcp/logging/logger.js

@@ -0,0 +1,22 @@
+/*
+ * 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
+ */
+/**
+ * Write a structured log entry to stderr.
+ * stdout is reserved exclusively for MCP JSON-RPC messages.
+ * IMPORTANT: data MUST NOT contain locator values, file content, or user PII.
+ */
+export function log(level, message, data) {
+    let entry;
+    try {
+        entry = JSON.stringify({ ts: new Date().toISOString(), level, message, ...data });
+    }
+    catch {
+        entry = JSON.stringify({ ts: new Date().toISOString(), level, message, logError: 'data not serializable' });
+    }
+    process.stderr.write(entry + '\n');
+}
+//# sourceMappingURL=logger.js.map

package/lib/mcp/logging/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/mcp/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAA8B;IAClF,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,CAAC,CAAC;IAC9G,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/lib/mcp/rules/page_object_validation_rules.json

@@ -0,0 +1,344 @@
+[
+  {
+    "id": "PO_001",
+    "name": "Missing package declaration",
+    "description": "Page Object is missing a package declaration.",
+    "penalty": 20,
+    "severity": "ERROR",
+    "appliesTo": "class",
+    "suggestion": "Add 'package pageobjects;' at the top of the file."
+  },
+  {
+    "id": "PO_002",
+    "name": "Invalid package name",
+    "description": "Package name format is invalid.",
+    "penalty": 18,
+    "severity": "ERROR",
+    "appliesTo": "class",
+    "suggestion": "Package names should be valid Java identifiers separated by dots (e.g., 'pageobjects' or 'pageobjects.MySubFolder')."
+  },
+  {
+    "id": "PO_003",
+    "name": "Missing class declaration",
+    "description": "Could not find public class declaration.",
+    "penalty": 25,
+    "severity": "ERROR",
+    "appliesTo": "class",
+    "suggestion": "Ensure the file has a 'public class ClassName' declaration."
+  },
+  {
+    "id": "PO_004",
+    "name": "Class name not PascalCase",
+    "description": "Class name should follow PascalCase naming convention.",
+    "penalty": 8,
+    "severity": "WARNING",
+    "appliesTo": "class",
+    "suggestion": "Rename class to use PascalCase (e.g., 'MyPageObject')."
+  },
+  {
+    "id": "PO_005",
+    "name": "Invalid class name",
+    "description": "Class name is not a valid Java identifier.",
+    "penalty": 20,
+    "severity": "ERROR",
+    "appliesTo": "class",
+    "suggestion": "Class names must start with a letter, $, or _ and contain only letters, digits, $, or _."
+  },
+  {
+    "id": "PO_006",
+    "name": "Class name mismatch",
+    "description": "Class name does not match the expected filename.",
+    "penalty": 18,
+    "severity": "ERROR",
+    "appliesTo": "class",
+    "suggestion": "Class name must match the filename."
+  },
+  {
+    "id": "PO_012",
+    "name": "Missing Provar annotations import",
+    "description": "Missing import for Provar annotations.",
+    "penalty": 10,
+    "severity": "WARNING",
+    "appliesTo": "class",
+    "suggestion": "Add 'import com.provar.core.testapi.annotations.*;'"
+  },
+  {
+    "id": "PO_020",
+    "name": "Missing @Page annotation",
+    "description": "Missing @Page or @SalesforcePage annotation.",
+    "penalty": 12,
+    "severity": "WARNING",
+    "appliesTo": "annotation",
+    "suggestion": "Add @Page annotation before the class declaration."
+  },
+  {
+    "id": "PO_021",
+    "name": "@Page missing title",
+    "description": "@Page annotation missing 'title' attribute.",
+    "penalty": 8,
+    "severity": "WARNING",
+    "appliesTo": "annotation",
+    "suggestion": "Add title attribute to @Page annotation."
+  },
+  {
+    "id": "PO_022",
+    "name": "@SalesforcePage missing required attribute",
+    "description": "@SalesforcePage annotation missing required 'title' or 'connection' attribute.",
+    "penalty": 18,
+    "severity": "ERROR",
+    "appliesTo": "annotation",
+    "suggestion": "Add required attributes to @SalesforcePage annotation."
+  },
+  {
+    "id": "PO_023",
+    "name": "@SalesforcePage missing page type",
+    "description": "@SalesforcePage should specify page type attribute.",
+    "penalty": 10,
+    "severity": "WARNING",
+    "appliesTo": "annotation",
+    "suggestion": "Add one of: page, auraComponent, object, or lightningWebComponent attribute."
+  },
+  {
+    "id": "PO_030",
+    "name": "No fields found",
+    "description": "No WebElement or WebComponent fields found in Page Object.",
+    "penalty": 12,
+    "severity": "WARNING",
+    "appliesTo": "class",
+    "suggestion": "Add at least one WebElement field with @FindBy locator and type annotation."
+  },
+  {
+    "id": "PO_031",
+    "name": "Duplicate field name",
+    "description": "Duplicate field name found within the same scope.",
+    "penalty": 20,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Rename one of the duplicate fields."
+  },
+  {
+    "id": "PO_032",
+    "name": "Invalid field name",
+    "description": "Field name is not a valid Java identifier.",
+    "penalty": 18,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Field names must be valid Java identifiers."
+  },
+  {
+    "id": "PO_033",
+    "name": "Reserved word field name",
+    "description": "Field name is a Java reserved word.",
+    "penalty": 20,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Rename field to avoid Java reserved words."
+  },
+  {
+    "id": "PO_034",
+    "name": "Invalid locator strategy",
+    "description": "Invalid locator strategy used in @FindBy annotation.",
+    "penalty": 18,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Use one of: xpath, id, css, name, className, tagName, linkText, partialLinkText, visualforce, label."
+  },
+  {
+    "id": "PO_035",
+    "name": "Empty locator",
+    "description": "Empty locator value for field (AI healing will populate at runtime).",
+    "penalty": 2,
+    "severity": "INFO",
+    "appliesTo": "field",
+    "suggestion": "Consider providing an initial locator value."
+  },
+  {
+    "id": "PO_036",
+    "name": "Invalid element type annotation",
+    "description": "Element type annotation is not a valid Provar type (e.g., @LookupType is not valid).",
+    "penalty": 10,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Use a valid Provar element type: TextType, ButtonType, LinkType, ChoiceListType, RadioType, FileType, DateType, RichTextType, BooleanType (NOTE: CheckboxType is invalid). For lookup/reference fields, use @TextType()."
+  },
+  {
+    "id": "PO_040",
+    "name": "Duplicate frame class name",
+    "description": "Duplicate @PageFrame class name found.",
+    "penalty": 20,
+    "severity": "ERROR",
+    "appliesTo": "frame",
+    "suggestion": "Rename one of the duplicate frame classes."
+  },
+  {
+    "id": "PO_041",
+    "name": "Frame class not PascalCase",
+    "description": "Frame class name should follow PascalCase naming convention.",
+    "penalty": 8,
+    "severity": "WARNING",
+    "appliesTo": "frame",
+    "suggestion": "Rename frame class to use PascalCase."
+  },
+  {
+    "id": "PO_050",
+    "name": "Missing semicolon",
+    "description": "Possible missing semicolon after field declaration.",
+    "penalty": 20,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Add semicolon after field declaration."
+  },
+  {
+    "id": "PO_051",
+    "name": "Unclosed string literal",
+    "description": "Possible unclosed string literal.",
+    "penalty": 10,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Check for missing closing quote."
+  },
+  {
+    "id": "PO_060",
+    "name": "Mismatched braces",
+    "description": "Mismatched opening and closing braces.",
+    "penalty": 25,
+    "severity": "ERROR",
+    "appliesTo": "class",
+    "suggestion": "Check for missing or extra curly braces."
+  },
+  {
+    "id": "PO_070",
+    "name": "ID-based locator",
+    "description": "Using 'id' locator strategy in Salesforce Lightning. IDs are often dynamically generated and unreliable.",
+    "penalty": 15,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Prefer xpath/css with stable attributes like data-testid, aria-label, name, or label-based locators."
+  },
+  {
+    "id": "PO_071",
+    "name": "Absolute XPath",
+    "description": "Absolute XPath starting from /html or /body. These break with any DOM structure change.",
+    "penalty": 20,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Use relative XPath starting with // or .// anchored to stable elements."
+  },
+  {
+    "id": "PO_072",
+    "name": "Indexed XPath",
+    "description": "XPath with numeric positional indexes like [1], [2], etc. These are brittle as they break when elements are added/removed.",
+    "penalty": 8,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Prefer attribute-based selection instead of positional indexes [n]."
+  },
+  {
+    "id": "PO_073",
+    "name": "Salesforce dynamic attribute",
+    "description": "Locators using Salesforce dynamic/Aura attributes (data-aura-rendered-by, aura-id, etc.). These change on every render and cause test flakiness.",
+    "penalty": 18,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Remove dynamic Aura attributes; use stable identifiers like labels, data-testid, or semantic selectors."
+  },
+  {
+    "id": "PO_074",
+    "name": "Hardcoded Salesforce ID",
+    "description": "Hardcoded Salesforce record IDs (15 or 18 character). These make tests environment-specific and non-portable.",
+    "penalty": 18,
+    "severity": "ERROR",
+    "appliesTo": "field",
+    "suggestion": "Remove hardcoded IDs; use dynamic data or environment-independent locators."
+  },
+  {
+    "id": "PO_075",
+    "name": "Unstable class pattern",
+    "description": "CSS class patterns that appear autogenerated or framework-specific. These classes often change with framework updates.",
+    "penalty": 5,
+    "severity": "INFO",
+    "appliesTo": "field",
+    "suggestion": "Prefer stable attributes over autogenerated CSS classes."
+  },
+  {
+    "id": "PO_076",
+    "name": "Complex XPath",
+    "description": "Overly complex XPath expressions with many path segments, axes, or predicates. Complex XPaths are harder to maintain and more likely to break.",
+    "penalty": 12,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Consider simplifying by using a more direct path, anchor + relative pattern, or data-testid attributes."
+  },
+  {
+    "id": "PO_077",
+    "name": "Text-based locator",
+    "description": "Locators that rely primarily on text content. Text-based locators may match multiple elements, fail with i18n changes, or break when labels are updated.",
+    "penalty": 5,
+    "severity": "INFO",
+    "appliesTo": "field",
+    "suggestion": "Combine text matching with other stable attributes; consider data-testid or aria-label."
+  },
+  {
+    "id": "PO_078",
+    "name": "Long locator",
+    "description": "Excessively long locators (>200 chars). Very long locators are harder to maintain and often indicate over-specification.",
+    "penalty": 3,
+    "severity": "INFO",
+    "appliesTo": "field",
+    "suggestion": "Consider using a shorter, more maintainable locator anchored to stable elements."
+  },
+  {
+    "id": "PO_079",
+    "name": "Position function in XPath",
+    "description": "XPath using position functions like last(), first(), position(). Position functions create fragile locators that break when DOM order changes.",
+    "penalty": 10,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Avoid position-based selection; use unique identifiers like @id, @data-testid, or aria attributes."
+  },
+  {
+    "id": "PO_080",
+    "name": "Commented code detected",
+    "description": "Page Object contains commented-out code. Commented code adds clutter and may indicate incomplete refactoring.",
+    "penalty": 2,
+    "severity": "INFO",
+    "appliesTo": "class",
+    "suggestion": "Remove commented code. Use version control to track code history instead."
+  },
+  {
+    "id": "PO_081",
+    "name": "Inline locator in method",
+    "description": "Locator defined inline within a method body using By.xpath(), By.id(), etc. Inline locators reduce maintainability and reusability.",
+    "penalty": 10,
+    "severity": "WARNING",
+    "appliesTo": "method",
+    "suggestion": "Extract inline locators to @FindBy WebElement fields at the class level for better maintainability and reuse."
+  },
+  {
+    "id": "PO_082",
+    "name": "Visualforce indexed component",
+    "description": "VisualforceBy locator uses positional index like [1], [2], [3]. Indexed locators break when page structure changes.",
+    "penalty": 8,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Use @id, @value, or @action attributes instead of positional indexes in componentXPath."
+  },
+  {
+    "id": "PO_083",
+    "name": "Visualforce not(@id) pattern",
+    "description": "VisualforceBy locator uses not(@id) pattern which matches any element without an ID. This is fragile and non-specific.",
+    "penalty": 10,
+    "severity": "WARNING",
+    "appliesTo": "field",
+    "suggestion": "Request developers add unique IDs to Visualforce components, or use more specific attributes like @value or @action."
+  },
+  {
+    "id": "PO_084",
+    "name": "Visualforce complex path",
+    "description": "VisualforceBy componentXPath contains complex nested path with multiple descendant selectors. Complex paths are harder to maintain.",
+    "penalty": 5,
+    "severity": "INFO",
+    "appliesTo": "field",
+    "suggestion": "Simplify the componentXPath by targeting a more specific ancestor component with @id or unique attributes."
+  }
+]