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

package/lib/mcp/tools/antTools.js

@@ -12,6 +12,7 @@ import { XMLParser } from 'fast-xml-parser';
 import { assertPathAllowed, PathPolicyError } from '../security/pathPolicy.js';
 import { makeError, makeRequestId } from '../schemas/common.js';
 import { log } from '../logging/logger.js';
+import { desc } from './descHelper.js';
 // ── Sub-schemas ───────────────────────────────────────────────────────────────
 const FilesetSchema = z.object({
     dir: z.string().describe('Directory path (relative or absolute) for the fileset'),
@@ -25,9 +26,7 @@ const FilesetSchema = z.object({
         .describe('Specific .testcase or .testplan file names to include (e.g. ["Login.testcase"]). Omit to run everything in dir.'),
 });
 const PlanFeatureSchema = z.object({
-    name: z
-        .enum(['PDF', 'PIECHART', 'EMAIL', 'JUNIT'])
-        .describe('Feature name (PDF, PIECHART, EMAIL, JUNIT)'),
+    name: z.enum(['PDF', 'PIECHART', 'EMAIL', 'JUNIT']).describe('Feature name (PDF, PIECHART, EMAIL, JUNIT)'),
     type: z.enum(['OUTPUT', 'NOTIFICATION']).describe('Feature type'),
     enabled: z.boolean().describe('Whether this feature is enabled'),
 });
@@ -56,148 +55,163 @@ const AttachmentPropertiesSchema = z.object({
 });
 // ── Generate tool ─────────────────────────────────────────────────────────────
 export function registerAntGenerate(server, config) {
-    server.tool('provar.ant.generate', [
-        'Generate a Provar ANT build.xml file.',
-        'Produces the standard <project> skeleton with Provar-Compile and Run-Test-Case tasks.',
-        'Supports targeting tests by project folder, plan folder, or specific .testcase files via filesets.',
-        'Returns XML content. Writes to disk only when dry_run=false.',
-    ].join(' '), {
-        // ── Core paths ──────────────────────────────────────────────────────────
-        provar_home: z
-            .string()
-            .describe('Absolute path to the Provar installation directory (e.g. "C:/Program Files/Provar/"). Used for provar.home property and ant taskdef classpaths.'),
-        project_path: z
-            .string()
-            .default('..')
-            .describe('Path to the Provar test project root. Defaults to ".." (parent of the ANT folder).'),
-        results_path: z
-            .string()
-            .default('../ANT/Results')
-            .describe('Path where test results are written. Defaults to "../ANT/Results".'),
-        project_cache_path: z
-            .string()
-            .optional()
-            .describe('Path to the .provarCaches directory. Defaults to "../../.provarCaches" relative to the ANT folder.'),
-        license_path: z
-            .string()
-            .optional()
-            .describe('Path to the Provar .licenses directory (e.g. "${env.PROVAR_HOME}/.licenses").'),
-        smtp_path: z
-            .string()
-            .optional()
-            .describe('Path to the Provar .smtp directory (e.g. "${env.PROVAR_HOME}/.smtp").'),
-        // ── Test selection ──────────────────────────────────────────────────────
-        filesets: z
-            .array(FilesetSchema)
-            .min(1)
-            .describe('One or more filesets defining which tests to run. ' +
-            'To run all tests under a folder: { dir: "../tests" }. ' +
-            'To run a plan: { id: "testplan", dir: "../plans/MyPlan" }. ' +
-            'To run specific test cases: { dir: "../tests/Suite", includes: ["MyTest.testcase"] }.'),
-        // ── Browser / environment ───────────────────────────────────────────────
-        web_browser: z
-            .enum(['Chrome', 'Chrome_Headless', 'Firefox', 'Edge', 'Edge_Legacy', 'Safari', 'IE'])
-            .default('Chrome')
-            .describe('Web browser to use for test execution.'),
-        web_browser_configuration: z
-            .string()
-            .default('Full Screen')
-            .describe('Browser window configuration (e.g. "Full Screen").'),
-        web_browser_provider_name: z
-            .string()
-            .default('Desktop')
-            .describe('Browser provider name (e.g. "Desktop").'),
-        web_browser_device_name: z
-            .string()
-            .default('Full Screen')
-            .describe('Browser device name (e.g. "Full Screen").'),
-        test_environment: z
-            .string()
-            .default('')
-            .describe('Named test environment to use (must match a connection in the project). Empty string uses default.'),
-        // ── Cache / metadata ────────────────────────────────────────────────────
-        salesforce_metadata_cache: z
-            .enum(['Reuse', 'Refresh', 'Reload'])
-            .default('Reuse')
-            .describe('Salesforce metadata cache strategy: Reuse (fastest, uses cached), Refresh (re-downloads), Reload (clears and re-downloads).'),
-        // ── Output / logging ────────────────────────────────────────────────────
-        results_path_disposition: z
-            .enum(['Increment', 'Replace', 'Reuse'])
-            .default('Increment')
-            .describe('How to handle the results folder when it already exists: Increment (new subfolder), Replace (overwrite), Reuse (append).'),
-        test_output_level: z
-            .enum(['BASIC', 'WARNING', 'DEBUG'])
-            .default('BASIC')
-            .describe('Verbosity level for test output logs.'),
-        plugin_output_level: z
-            .enum(['BASIC', 'WARNING', 'DEBUG'])
-            .default('WARNING')
-            .describe('Verbosity level for plugin output logs.'),
-        // ── Execution behaviour ─────────────────────────────────────────────────
-        stop_test_run_on_error: z
-            .boolean()
-            .default(false)
-            .describe('Abort the entire test run when any test case fails.'),
-        exclude_callable_test_cases: z
-            .boolean()
-            .default(true)
-            .describe('Skip test cases marked as callable (library/helper) when true.'),
-        dont_fail_build: z
-            .boolean()
-            .optional()
-            .describe('When true, the ANT build does not fail even if tests fail. Useful for CI pipelines that collect results separately.'),
-        invoke_test_run_monitor: z
-            .boolean()
-            .default(true)
-            .describe('Enable the Provar test run monitor.'),
-        // ── Secrets / security ──────────────────────────────────────────────────
-        secrets_password: z
-            .string()
-            .default('${env.ProvarSecretsPassword}')
-            .describe('Password for the Provar secrets store. Defaults to reading from the ProvarSecretsPassword environment variable.'),
-        test_environment_secrets_password: z
-            .string()
-            .optional()
-            .describe('Per-environment secrets password. Defaults to reading from the ProvarSecretsPassword_EnvName environment variable.'),
-        // ── Test Cycle ──────────────────────────────────────────────────────────
-        test_cycle_path: z
-            .string()
-            .optional()
-            .describe('Path to a TestCycle folder (used with test cycle reporting).'),
-        test_cycle_run_type: z
-            .enum(['ALL', 'FAILED', 'NEW'])
-            .optional()
-            .describe('Which tests in the cycle to run (ALL, FAILED, NEW).'),
-        // ── Plan features ───────────────────────────────────────────────────────
-        plan_features: z
-            .array(PlanFeatureSchema)
-            .optional()
-            .describe('Output and notification features to enable/disable (e.g. PDF, PIECHART, EMAIL). ' +
-            'Only meaningful when running by test plan.'),
-        // ── Email / attachment reporting ────────────────────────────────────────
-        email_properties: EmailPropertiesSchema.optional().describe('Email notification settings. Omit to exclude <emailProperties> from the XML.'),
-        attachment_properties: AttachmentPropertiesSchema.optional().describe('Attachment/report content settings. Omit to exclude <attachmentProperties> from the XML.'),
-        // ── File output ─────────────────────────────────────────────────────────
-        output_path: z
-            .string()
-            .optional()
-            .describe('Where to write the build.xml file (returned in response). Required when dry_run=false.'),
-        overwrite: z
-            .boolean()
-            .default(false)
-            .describe('Overwrite output_path if the file already exists.'),
-        dry_run: z
-            .boolean()
-            .default(true)
-            .describe('true = return XML only (default); false = write to output_path.'),
+    server.registerTool('provar_ant_generate', {
+        title: 'Generate ANT Build File',
+        description: desc([
+            'Generate a Provar ANT build.xml file.',
+            'Produces the standard <project> skeleton with Provar-Compile and Run-Test-Case tasks.',
+            'Supports targeting tests by project folder, plan folder, or specific .testcase files via filesets.',
+            'Returns XML content. Writes to disk only when dry_run=false.',
+        ].join(' '), 'Generate a Provar ANT build.xml with Provar-Compile and Run-Test-Case tasks.'),
+        inputSchema: {
+            // ── Core paths ──────────────────────────────────────────────────────────
+            provar_home: z
+                .string()
+                .describe(desc('Absolute path to the Provar installation directory (e.g. "C:/Program Files/Provar/"). Used for provar.home property and ant taskdef classpaths.', 'string, absolute path to Provar installation')),
+            project_path: z
+                .string()
+                .default('..')
+                .describe(desc('Path to the Provar test project root. Defaults to ".." (parent of the ANT folder).', 'string, path to project root')),
+            results_path: z
+                .string()
+                .default('../ANT/Results')
+                .describe(desc('Path where test results are written. Defaults to "../ANT/Results".', 'string, path for test results')),
+            project_cache_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the .provarCaches directory. Defaults to "../../.provarCaches" relative to the ANT folder.', 'string, optional; path to .provarCaches')),
+            license_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the Provar .licenses directory (e.g. "${env.PROVAR_HOME}/.licenses").', 'string, optional; path to .licenses dir')),
+            smtp_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the Provar .smtp directory (e.g. "${env.PROVAR_HOME}/.smtp").', 'string, optional; path to .smtp dir')),
+            // ── Test selection ──────────────────────────────────────────────────────
+            filesets: z
+                .array(FilesetSchema)
+                .min(1)
+                .describe(desc('One or more filesets defining which tests to run. ' +
+                'To run all tests under a folder: { dir: "../tests" }. ' +
+                'To run a plan: { id: "testplan", dir: "../plans/MyPlan" }. ' +
+                'To run specific test cases: { dir: "../tests/Suite", includes: ["MyTest.testcase"] }.', 'array, min 1; filesets defining which tests to run')),
+            // ── Browser / environment ───────────────────────────────────────────────
+            web_browser: z
+                .enum(['Chrome', 'Chrome_Headless', 'Firefox', 'Edge', 'Edge_Legacy', 'Safari', 'IE'])
+                .default('Chrome')
+                .describe(desc('Web browser to use for test execution.', 'enum Chrome|Chrome_Headless|Firefox|Edge|Safari|IE')),
+            web_browser_configuration: z
+                .string()
+                .default('Full Screen')
+                .describe(desc('Browser window configuration (e.g. "Full Screen").', 'string, browser window config')),
+            web_browser_provider_name: z
+                .string()
+                .default('Desktop')
+                .describe(desc('Browser provider name (e.g. "Desktop").', 'string, browser provider name')),
+            web_browser_device_name: z
+                .string()
+                .default('Full Screen')
+                .describe(desc('Browser device name (e.g. "Full Screen").', 'string, browser device name')),
+            test_environment: z
+                .string()
+                .default('')
+                .describe(desc('Named test environment to use (must match a connection in the project). Empty string uses default.', 'string, optional; named test environment')),
+            // ── Cache / metadata ────────────────────────────────────────────────────
+            salesforce_metadata_cache: z
+                .enum(['Reuse', 'Refresh', 'Reload'])
+                .default('Reuse')
+                .describe(desc('Salesforce metadata cache strategy: Reuse (fastest, uses cached), Refresh (re-downloads), Reload (clears and re-downloads).', 'enum Reuse|Refresh|Reload')),
+            // ── Output / logging ────────────────────────────────────────────────────
+            results_path_disposition: z
+                .enum(['Increment', 'Replace', 'Reuse'])
+                .default('Increment')
+                .describe(desc('How to handle the results folder when it already exists: Increment (new subfolder), Replace (overwrite), Reuse (append).', 'enum Increment|Replace|Reuse')),
+            test_output_level: z
+                .enum(['BASIC', 'WARNING', 'DEBUG'])
+                .default('BASIC')
+                .describe(desc('Verbosity level for test output logs.', 'enum BASIC|WARNING|DEBUG')),
+            plugin_output_level: z
+                .enum(['BASIC', 'WARNING', 'DEBUG'])
+                .default('WARNING')
+                .describe(desc('Verbosity level for plugin output logs.', 'enum BASIC|WARNING|DEBUG')),
+            // ── Execution behaviour ─────────────────────────────────────────────────
+            stop_test_run_on_error: z
+                .boolean()
+                .default(false)
+                .describe(desc('Abort the entire test run when any test case fails.', 'bool, optional; abort on failure')),
+            exclude_callable_test_cases: z
+                .boolean()
+                .default(true)
+                .describe(desc('Skip test cases marked as callable (library/helper) when true.', 'bool, optional; skip callable tests')),
+            dont_fail_build: z
+                .boolean()
+                .optional()
+                .describe(desc('When true, the ANT build does not fail even if tests fail. Useful for CI pipelines that collect results separately.', 'bool, optional; skip build failure on test fail')),
+            invoke_test_run_monitor: z
+                .boolean()
+                .default(true)
+                .describe(desc('Enable the Provar test run monitor.', 'bool, optional; enable test run monitor')),
+            // ── Secrets / security ──────────────────────────────────────────────────
+            secrets_password: z
+                .string()
+                .default('${env.ProvarSecretsPassword}')
+                .describe(desc('Encryption key used to decrypt the Provar .secrets file (the password string itself, not a file path). Defaults to reading from the ProvarSecretsPassword environment variable.', 'string, NOT a file path; encryption key for .secrets')),
+            test_environment_secrets_password: z
+                .string()
+                .optional()
+                .describe(desc('Per-environment secrets password. Defaults to reading from the ProvarSecretsPassword_EnvName environment variable.', 'string, optional; per-environment secrets key')),
+            // ── Test Cycle ──────────────────────────────────────────────────────────
+            test_cycle_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to a TestCycle folder (used with test cycle reporting).', 'string, optional; path to TestCycle folder')),
+            test_cycle_run_type: z
+                .enum(['ALL', 'FAILED', 'NEW'])
+                .optional()
+                .describe(desc('Which tests in the cycle to run (ALL, FAILED, NEW).', 'enum ALL|FAILED|NEW, optional')),
+            // ── Plan features ───────────────────────────────────────────────────────
+            plan_features: z
+                .array(PlanFeatureSchema)
+                .optional()
+                .describe(desc('Output and notification features to enable/disable (e.g. PDF, PIECHART, EMAIL). ' +
+                'Only meaningful when running by test plan.', 'array, optional; plan output/notification features')),
+            // ── Email / attachment reporting ────────────────────────────────────────
+            email_properties: EmailPropertiesSchema.optional().describe(desc('Email notification settings. Omit to exclude <emailProperties> from the XML.', 'object, optional; email notification settings')),
+            attachment_properties: AttachmentPropertiesSchema.optional().describe(desc('Attachment/report content settings. Omit to exclude <attachmentProperties> from the XML.', 'object, optional; attachment/report content settings')),
+            // ── File output ─────────────────────────────────────────────────────────
+            output_path: z
+                .string()
+                .optional()
+                .describe(desc('Where to write the build.xml file (returned in response). Required when dry_run=false.', 'string, optional; absolute path for build.xml output')),
+            overwrite: z
+                .boolean()
+                .default(false)
+                .describe(desc('Overwrite output_path if the file already exists.', 'bool, optional; overwrite if exists')),
+            dry_run: z
+                .boolean()
+                .default(true)
+                .describe(desc('true = return XML only (default); false = write to output_path.', 'bool, optional; true=return only, false=write')),
+        },
     }, (input) => {
         const requestId = makeRequestId();
-        log('info', 'provar.ant.generate', {
+        log('info', 'provar_ant_generate', {
             requestId,
             output_path: input.output_path,
             dry_run: input.dry_run,
         });
         try {
+            // Validate all path inputs before writing anything — these get embedded in the
+            // generated ANT build.xml and would be accessed by ANT at execution time.
+            assertPathAllowed(input.provar_home, config.allowedPaths);
+            assertPathAllowed(input.project_path, config.allowedPaths);
+            assertPathAllowed(input.results_path, config.allowedPaths);
+            if (input.license_path)
+                assertPathAllowed(input.license_path, config.allowedPaths);
+            if (input.smtp_path)
+                assertPathAllowed(input.smtp_path, config.allowedPaths);
+            if (input.project_cache_path)
+                assertPathAllowed(input.project_cache_path, config.allowedPaths);
             const xmlContent = buildAntXml(input);
             const filePath = input.output_path ? path.resolve(input.output_path) : undefined;
             let written = false;
@@ -210,7 +224,7 @@ export function registerAntGenerate(server, config) {
                 fs.mkdirSync(path.dirname(filePath), { recursive: true });
                 fs.writeFileSync(filePath, xmlContent, 'utf-8');
                 written = true;
-                log('info', 'provar.ant.generate: wrote file', { requestId, filePath });
+                log('info', 'provar_ant_generate: wrote file', { requestId, filePath });
             }
             const result = {
                 requestId,
@@ -226,31 +240,35 @@ export function registerAntGenerate(server, config) {
         }
         catch (err) {
             const error = err;
-            const errResult = makeError(error instanceof PathPolicyError ? error.code : (error.code ?? 'GENERATE_ERROR'), error.message, requestId, false);
-            log('error', 'provar.ant.generate failed', { requestId, error: error.message });
+            const errResult = makeError(error instanceof PathPolicyError ? error.code : error.code ?? 'GENERATE_ERROR', error.message, requestId, false);
+            log('error', 'provar_ant_generate failed', { requestId, error: error.message });
             return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
         }
     });
 }
 // ── Validate tool ─────────────────────────────────────────────────────────────
 export function registerAntValidate(server, config) {
-    server.tool('provar.ant.validate', [
-        'Validate a Provar ANT build.xml for structural correctness.',
-        'Checks XML well-formedness, required <taskdef> declarations, <Provar-Compile> step,',
-        '<Run-Test-Case> with required attributes (provarHome, projectPath, resultsPath),',
-        'and at least one <fileset> child. Returns is_valid, issues list, and a validity_score.',
-    ].join(' '), {
-        content: z
-            .string()
-            .optional()
-            .describe('XML content to validate directly'),
-        file_path: z
-            .string()
-            .optional()
-            .describe('Path to the build.xml file to validate'),
+    server.registerTool('provar_ant_validate', {
+        title: 'Validate ANT Build File',
+        description: desc([
+            'Validate a Provar ANT build.xml for structural correctness.',
+            'Checks XML well-formedness, required <taskdef> declarations, <Provar-Compile> step,',
+            '<Run-Test-Case> with required attributes (provarHome, projectPath, resultsPath),',
+            'and at least one <fileset> child. Returns is_valid, issues list, and a validity_score.',
+        ].join(' '), 'Validate a Provar ANT build.xml for structural correctness.'),
+        inputSchema: {
+            content: z
+                .string()
+                .optional()
+                .describe(desc('XML content to validate directly', 'string, optional; inline XML')),
+            file_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the build.xml file to validate', 'string, optional; absolute path to build.xml')),
+        },
     }, ({ content, file_path }) => {
         const requestId = makeRequestId();
-        log('info', 'provar.ant.validate', { requestId, has_content: !!content, file_path });
+        log('info', 'provar_ant_validate', { requestId, has_content: !!content, file_path });
         try {
             let source = content;
             if (!source && file_path) {
@@ -276,7 +294,7 @@ export function registerAntValidate(server, config) {
         catch (err) {
             const error = err;
             const errResult = makeError(error instanceof PathPolicyError ? error.code : 'VALIDATE_ERROR', error.message, requestId, false);
-            log('error', 'provar.ant.validate failed', { requestId, error: error.message });
+            log('error', 'provar_ant_validate failed', { requestId, error: error.message });
             return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
         }
     });
@@ -393,13 +411,11 @@ function escapeXmlAttr(value) {
     return value
         .replace(/&/g, '&amp;')
         .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;')
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-const REQUIRED_TASKDEF_CLASSNAMES = [
-    'com.provar.testrunner.ant.CompileTask',
-    'com.provar.testrunner.ant.RunnerTask',
-];
+const REQUIRED_TASKDEF_CLASSNAMES = ['com.provar.testrunner.ant.CompileTask', 'com.provar.testrunner.ant.RunnerTask'];
 const VALID_BROWSERS = ['Chrome', 'Chrome_Headless', 'Firefox', 'Edge', 'Edge_Legacy', 'Safari', 'IE'];
 const VALID_CACHE = ['Reuse', 'Refresh', 'Reload'];
 const VALID_OUTPUT_LEVELS = ['BASIC', 'WARNING', 'DEBUG'];
@@ -456,19 +472,43 @@ function validateProjectStructure(project, defaultTarget, issues) {
 }
 function validateRtcEnumAttrs(rtc, webBrowser, issues) {
     if (webBrowser && !VALID_BROWSERS.includes(webBrowser)) {
-        issues.push({ rule_id: 'ANT_030', severity: 'WARNING', message: `webBrowser "${webBrowser}" is not a recognised value. Expected one of: ${VALID_BROWSERS.join(', ')}.`, applies_to: 'Run-Test-Case', suggestion: `Use one of the supported browser values: ${VALID_BROWSERS.join(', ')}.` });
+        issues.push({
+            rule_id: 'ANT_030',
+            severity: 'WARNING',
+            message: `webBrowser "${webBrowser}" is not a recognised value. Expected one of: ${VALID_BROWSERS.join(', ')}.`,
+            applies_to: 'Run-Test-Case',
+            suggestion: `Use one of the supported browser values: ${VALID_BROWSERS.join(', ')}.`,
+        });
     }
     const metadataCache = rtc['@_salesforceMetadataCache'];
     if (metadataCache && !VALID_CACHE.includes(metadataCache)) {
-        issues.push({ rule_id: 'ANT_031', severity: 'WARNING', message: `salesforceMetadataCache "${metadataCache}" is not a recognised value. Expected one of: ${VALID_CACHE.join(', ')}.`, applies_to: 'Run-Test-Case', suggestion: `Use one of: ${VALID_CACHE.join(', ')}.` });
+        issues.push({
+            rule_id: 'ANT_031',
+            severity: 'WARNING',
+            message: `salesforceMetadataCache "${metadataCache}" is not a recognised value. Expected one of: ${VALID_CACHE.join(', ')}.`,
+            applies_to: 'Run-Test-Case',
+            suggestion: `Use one of: ${VALID_CACHE.join(', ')}.`,
+        });
     }
     const testOutputLevel = rtc['@_testOutputlevel'];
     if (testOutputLevel && !VALID_OUTPUT_LEVELS.includes(testOutputLevel)) {
-        issues.push({ rule_id: 'ANT_032', severity: 'WARNING', message: `testOutputlevel "${testOutputLevel}" is not a recognised value. Expected one of: ${VALID_OUTPUT_LEVELS.join(', ')}.`, applies_to: 'Run-Test-Case', suggestion: `Use one of: ${VALID_OUTPUT_LEVELS.join(', ')}.` });
+        issues.push({
+            rule_id: 'ANT_032',
+            severity: 'WARNING',
+            message: `testOutputlevel "${testOutputLevel}" is not a recognised value. Expected one of: ${VALID_OUTPUT_LEVELS.join(', ')}.`,
+            applies_to: 'Run-Test-Case',
+            suggestion: `Use one of: ${VALID_OUTPUT_LEVELS.join(', ')}.`,
+        });
     }
     const disposition = rtc['@_resultsPathDisposition'];
     if (disposition && !VALID_DISPOSITIONS.includes(disposition)) {
-        issues.push({ rule_id: 'ANT_033', severity: 'WARNING', message: `resultsPathDisposition "${disposition}" is not a recognised value. Expected one of: ${VALID_DISPOSITIONS.join(', ')}.`, applies_to: 'Run-Test-Case', suggestion: `Use one of: ${VALID_DISPOSITIONS.join(', ')}.` });
+        issues.push({
+            rule_id: 'ANT_033',
+            severity: 'WARNING',
+            message: `resultsPathDisposition "${disposition}" is not a recognised value. Expected one of: ${VALID_DISPOSITIONS.join(', ')}.`,
+            applies_to: 'Run-Test-Case',
+            suggestion: `Use one of: ${VALID_DISPOSITIONS.join(', ')}.`,
+        });
     }
 }
 function validateRunTestCase(rtc, issues) {
@@ -478,22 +518,52 @@ function validateRunTestCase(rtc, issues) {
     const webBrowser = rtc['@_webBrowser'] ?? null;
     const testEnvironment = rtc['@_testEnvironment'] ?? null;
     if (!provarHome) {
-        issues.push({ rule_id: 'ANT_021', severity: 'ERROR', message: '<Run-Test-Case> missing required "provarHome" attribute.', applies_to: 'Run-Test-Case', suggestion: 'Add provarHome="${provar.home}" to <Run-Test-Case>.' });
+        issues.push({
+            rule_id: 'ANT_021',
+            severity: 'ERROR',
+            message: '<Run-Test-Case> missing required "provarHome" attribute.',
+            applies_to: 'Run-Test-Case',
+            suggestion: 'Add provarHome="${provar.home}" to <Run-Test-Case>.',
+        });
     }
     if (!projectPath) {
-        issues.push({ rule_id: 'ANT_022', severity: 'ERROR', message: '<Run-Test-Case> missing required "projectPath" attribute.', applies_to: 'Run-Test-Case', suggestion: 'Add projectPath="${testproject.home}" to <Run-Test-Case>.' });
+        issues.push({
+            rule_id: 'ANT_022',
+            severity: 'ERROR',
+            message: '<Run-Test-Case> missing required "projectPath" attribute.',
+            applies_to: 'Run-Test-Case',
+            suggestion: 'Add projectPath="${testproject.home}" to <Run-Test-Case>.',
+        });
     }
     if (!resultsPath) {
-        issues.push({ rule_id: 'ANT_023', severity: 'ERROR', message: '<Run-Test-Case> missing required "resultsPath" attribute.', applies_to: 'Run-Test-Case', suggestion: 'Add resultsPath="${testproject.results}" to <Run-Test-Case>.' });
+        issues.push({
+            rule_id: 'ANT_023',
+            severity: 'ERROR',
+            message: '<Run-Test-Case> missing required "resultsPath" attribute.',
+            applies_to: 'Run-Test-Case',
+            suggestion: 'Add resultsPath="${testproject.results}" to <Run-Test-Case>.',
+        });
     }
     validateRtcEnumAttrs(rtc, webBrowser, issues);
     const filesets = rtc['fileset'] ?? [];
     if (filesets.length === 0) {
-        issues.push({ rule_id: 'ANT_040', severity: 'ERROR', message: '<Run-Test-Case> has no <fileset> children — no tests will be selected.', applies_to: 'Run-Test-Case', suggestion: 'Add at least one <fileset dir="..."/> pointing to your tests or plans folder.' });
+        issues.push({
+            rule_id: 'ANT_040',
+            severity: 'ERROR',
+            message: '<Run-Test-Case> has no <fileset> children — no tests will be selected.',
+            applies_to: 'Run-Test-Case',
+            suggestion: 'Add at least one <fileset dir="..."/> pointing to your tests or plans folder.',
+        });
     }
     for (const [i, fsEntry] of filesets.entries()) {
         if (!fsEntry['@_dir']) {
-            issues.push({ rule_id: 'ANT_041', severity: 'ERROR', message: `<fileset> at index ${i} is missing required "dir" attribute.`, applies_to: 'fileset', suggestion: 'Add dir="..." to each <fileset> element.' });
+            issues.push({
+                rule_id: 'ANT_041',
+                severity: 'ERROR',
+                message: `<fileset> at index ${i} is missing required "dir" attribute.`,
+                applies_to: 'fileset',
+                suggestion: 'Add dir="..." to each <fileset> element.',
+            });
         }
     }
     return { provarHome, projectPath, resultsPath, webBrowser, testEnvironment, filesetCount: filesets.length };
@@ -594,6 +664,135 @@ function finalizeAnt(issues, provarHome, projectPath, resultsPath, webBrowser, t
         issues,
     };
 }
+function extractFailureText(el) {
+    if (!el)
+        return undefined;
+    if (typeof el === 'string')
+        return el.trim() || undefined;
+    if (typeof el === 'object') {
+        const obj = el;
+        // Prefer CDATA body ('#text') — it has the specific error. Fall back to 'message' attribute.
+        const body = obj['#text']?.trim();
+        const msg = obj['message']?.trim();
+        if (body && msg && body !== msg)
+            return `${msg}: ${body}`;
+        return body ?? msg;
+    }
+    return undefined;
+}
+function extractStepsFromJUnit(parsed) {
+    const steps = [];
+    let idx = 0;
+    // Normalise to array of suites — handles both <testsuites> and bare <testsuite>
+    let suites = [];
+    if (parsed['testsuites']) {
+        const inner = parsed['testsuites']['testsuite'];
+        suites = Array.isArray(inner)
+            ? inner
+            : inner
+                ? [inner]
+                : [];
+    }
+    else if (parsed['testsuite']) {
+        const ts = parsed['testsuite'];
+        suites = Array.isArray(ts) ? ts : [ts];
+    }
+    for (const suite of suites) {
+        const rawTc = suite['testcase'];
+        if (!rawTc)
+            continue;
+        const testcases = Array.isArray(rawTc)
+            ? rawTc
+            : [rawTc];
+        for (const tc of testcases) {
+            idx++;
+            // Provar JUnit: name = test case file name (no attribute prefix since attributeNamePrefix: '')
+            const title = tc['name'] ?? `Test ${idx}`;
+            const hasFailure = 'failure' in tc || 'error' in tc;
+            const hasSkipped = 'skipped' in tc;
+            let status = 'pass';
+            if (hasFailure)
+                status = 'fail';
+            else if (hasSkipped)
+                status = 'skip';
+            const errorMessage = extractFailureText(tc['failure'] ?? tc['error']);
+            const step = { testItemId: String(idx), title, status };
+            if (errorMessage)
+                step.errorMessage = errorMessage;
+            steps.push(step);
+        }
+    }
+    return steps;
+}
+function findXmlFiles(dir) {
+    const results = [];
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith('.xml') && !entry.name.startsWith('.')) {
+                results.push(path.join(dir, entry.name));
+            }
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return results;
+}
+/**
+ * Scan a Provar results directory for JUnit XML files and return structured step results.
+ * Returns an empty steps array (+ optional warning) when no XML is found or parsing fails.
+ */
+export function parseJUnitResults(resultsDir) {
+    if (!fs.existsSync(resultsDir)) {
+        return { steps: [], warning: `Results directory not found: ${resultsDir}` };
+    }
+    const xmlFiles = findXmlFiles(resultsDir);
+    if (xmlFiles.length === 0) {
+        return {
+            steps: [],
+            warning: 'No JUnit XML files found in results directory — structured step output unavailable.',
+        };
+    }
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: '',
+        textNodeName: '#text',
+        allowBooleanAttributes: true,
+        parseAttributeValue: false,
+        isArray: (tagName) => ['testsuite', 'testcase'].includes(tagName),
+    });
+    const allSteps = [];
+    let parsedAny = false;
+    let parseFailures = 0;
+    for (const xmlFile of xmlFiles) {
+        try {
+            const content = fs.readFileSync(xmlFile, 'utf-8');
+            const parsed = parser.parse(content);
+            const steps = extractStepsFromJUnit(parsed);
+            allSteps.push(...steps);
+            parsedAny = true;
+        }
+        catch {
+            parseFailures++;
+        }
+    }
+    if (!parsedAny) {
+        return {
+            steps: [],
+            warning: 'JUnit XML files found but could not be parsed — structured step output unavailable.',
+        };
+    }
+    if (allSteps.length === 0) {
+        return {
+            steps: [],
+            warning: 'JUnit XML found but no test steps could be extracted — files may not be standard JUnit format.',
+        };
+    }
+    const warning = parseFailures > 0
+        ? `${parseFailures} JUnit XML file(s) could not be parsed — step data may be incomplete.`
+        : undefined;
+    return { steps: allSteps, warning };
+}
 // ── Registration ──────────────────────────────────────────────────────────────
 export function registerAllAntTools(server, config) {
     registerAntGenerate(server, config);