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

package/lib/mcp/tools/automationTools.js

@@ -11,221 +11,359 @@ import path from 'node:path';
 import { z } from 'zod';
 import { makeError, makeRequestId } from '../schemas/common.js';
 import { log } from '../logging/logger.js';
-import { sfSpawnHelper } from './sfSpawn.js';
-// ── SF CLI discovery ──────────────────────────────────────────────────────────
-/**
- * Returns candidate sf CLI paths in common npm/nvm/volta install locations.
- * Used as a fallback when `sf` is not in PATH.
- */
-export function getSfCommonPaths() {
-    const home = os.homedir();
-    if (process.platform === 'win32') {
-        const appData = process.env['APPDATA'] ?? path.join(home, 'AppData', 'Roaming');
-        return [
-            path.join(appData, 'npm', 'sf.cmd'),
-            path.join('C:', 'Program Files', 'nodejs', 'sf.cmd'),
-            path.join('C:', 'Program Files (x86)', 'nodejs', 'sf.cmd'),
-        ];
-    }
-    const candidates = [
-        '/usr/local/bin/sf',
-        path.join(home, '.npm-global', 'bin', 'sf'),
-        path.join(home, '.local', 'bin', 'sf'),
-        path.join(home, '.volta', 'bin', 'sf'),
-    ];
-    // nvm — scan the three most-recently installed Node versions
-    const nvmBinDir = path.join(process.env['NVM_DIR'] ?? path.join(home, '.nvm'), 'versions', 'node');
-    if (fs.existsSync(nvmBinDir)) {
-        try {
-            for (const v of fs.readdirSync(nvmBinDir).sort().reverse().slice(0, 3)) {
-                candidates.push(path.join(nvmBinDir, v, 'bin', 'sf'));
-            }
-        }
-        catch { /* skip */ }
-    }
-    return candidates;
-}
-// ── Shared spawn helper ───────────────────────────────────────────────────────
-const MAX_BUFFER = 50 * 1024 * 1024; // 50 MB — prevents ENOBUFS on verbose Provar runs
-// Proactively resolve the sf executable path once on first use and cache it.
-// This ensures sf is always found even when ENOENT is masked by other errors (e.g. ENOBUFS).
-let cachedSfPath; // undefined = not yet probed
-/** Exposed for testing only — pre-seeds the cached sf executable path, bypassing the probe spawn. */
-export function setSfPathCacheForTesting(value) {
-    cachedSfPath = value;
-}
-function resolveSfExecutable() {
-    if (cachedSfPath !== undefined)
-        return cachedSfPath;
-    // Check PATH first via a cheap version probe
-    const probe = sfSpawnHelper.spawnSync('sf', ['--version'], { encoding: 'utf-8', shell: false, maxBuffer: 1024 * 1024 });
-    if (!probe.error) {
-        cachedSfPath = 'sf';
-        return cachedSfPath;
-    }
-    // Fall back to common install locations
-    for (const candidate of getSfCommonPaths()) {
-        if (fs.existsSync(candidate)) {
-            cachedSfPath = candidate;
-            return cachedSfPath;
-        }
-    }
-    cachedSfPath = null;
-    return null;
-}
-class SfNotFoundError extends Error {
-    code = 'SF_NOT_FOUND';
-    constructor(sfPath) {
-        const where = sfPath
-            ? `at explicit path "${sfPath}"`
-            : 'in PATH or common npm/nvm install locations';
-        super(`sf CLI not found ${where}. ` +
-            'Install Salesforce CLI (npm install -g @salesforce/cli) and ensure the install directory is in your PATH, ' +
-            'or pass sf_path pointing to the sf executable directly ' +
-            '(e.g. "~/.nvm/versions/node/v22.0.0/bin/sf").');
-    }
-}
-function runSfCommand(args, sfPath) {
-    // Use explicit path if provided; otherwise use cached probe result
-    const executable = sfPath ?? resolveSfExecutable();
-    if (!executable)
-        throw new SfNotFoundError();
-    const result = sfSpawnHelper.spawnSync(executable, args, { encoding: 'utf-8', shell: false, maxBuffer: MAX_BUFFER });
-    if (result.error) {
-        const err = result.error;
-        if (err.code === 'ENOENT') {
-            throw new SfNotFoundError(sfPath);
-        }
-        throw result.error;
-    }
-    return {
-        stdout: result.stdout ?? '',
-        stderr: result.stderr ?? '',
-        exitCode: result.status ?? 1,
-    };
-}
+import { assertPathAllowed, PathPolicyError } from '../security/pathPolicy.js';
+import { parseJUnitResults } from './antTools.js';
+import { runSfCommand } from './sfSpawn.js';
+import { desc } from './descHelper.js';
+// Re-export sf resolution helpers so existing test imports from automationTools continue to work
+export { getSfCommonPaths, needsWindowsShell, setSfPathCacheForTesting, setSfPlatformForTesting } from './sfSpawn.js';
 function handleSpawnError(err, requestId, toolName) {
     const error = err;
     log('error', `${toolName} failed`, { requestId, error: error.message });
     return {
         isError: true,
-        content: [{ type: 'text', text: JSON.stringify(makeError(error.code ?? 'SF_ERROR', error.message, requestId, false)) }],
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(makeError(error.code ?? 'SF_ERROR', error.message, requestId, false)),
+            },
+        ],
     };
 }
-// ── Tool: provar.automation.config.load ──────────────────────────────────────
-export function registerAutomationConfigLoad(server) {
-    server.tool('provar.automation.config.load', [
-        'Register a provardx-properties.json file as the active Provar configuration.',
-        'Invokes `sf provar automation config load --properties-file <path>`, writing the path to ~/.sf/config.json.',
-        'REQUIRED before provar.automation.compile or provar.automation.testrun — without this step those commands fail with MISSING_FILE.',
-        'Typical workflow: provar.automation.config.load → provar.automation.compile → provar.automation.testrun.',
-    ].join(' '), {
-        properties_path: z.string().describe('Absolute path to the provardx-properties.json file to register as active configuration'),
-        sf_path: z.string().optional().describe('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")'),
+// ── Tool: provar_automation_config_load ──────────────────────────────────────
+export function registerAutomationConfigLoad(server, config) {
+    server.registerTool('provar_automation_config_load', {
+        title: 'Load Automation Config',
+        description: desc([
+            'Register a provardx-properties.json file as the active Provar configuration.',
+            'Invokes `sf provar automation config load --properties-file <path>`, writing the path to ~/.sf/config.json.',
+            'REQUIRED before provar_automation_compile or provar_automation_testrun — without this step those commands fail with MISSING_FILE.',
+            'Typical workflow: provar_automation_config_load → provar_automation_compile → provar_automation_testrun.',
+        ].join(' '), 'Register a provardx-properties.json as active config; required before compile/testrun.'),
+        inputSchema: {
+            properties_path: z
+                .string()
+                .describe(desc('Absolute path to the provardx-properties.json file to register as active configuration', 'string, absolute path to provardx-properties.json')),
+            sf_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")', 'string, optional; path to sf CLI')),
+        },
     }, ({ properties_path, sf_path }) => {
         const requestId = makeRequestId();
-        log('info', 'provar.automation.config.load', { requestId, properties_path });
+        log('info', 'provar_automation_config_load', { requestId, properties_path });
         try {
+            assertPathAllowed(properties_path, config.allowedPaths);
             const result = runSfCommand(['provar', 'automation', 'config', 'load', '--properties-file', properties_path], sf_path);
-            const response = { requestId, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, properties_path };
+            const response = {
+                requestId,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                properties_path,
+            };
             if (result.exitCode !== 0) {
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify(makeError('AUTOMATION_CONFIG_LOAD_FAILED', result.stderr || result.stdout, requestId)) }] };
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(makeError('AUTOMATION_CONFIG_LOAD_FAILED', result.stderr || result.stdout, requestId)),
+                        },
+                    ],
+                };
             }
             return { content: [{ type: 'text', text: JSON.stringify(response) }], structuredContent: response };
         }
         catch (err) {
-            return handleSpawnError(err, requestId, 'provar.automation.config.load');
+            if (err instanceof PathPolicyError) {
+                return {
+                    isError: true,
+                    content: [
+                        { type: 'text', text: JSON.stringify(makeError(err.code, err.message, requestId, false)) },
+                    ],
+                };
+            }
+            return handleSpawnError(err, requestId, 'provar_automation_config_load');
         }
     });
 }
-// ── Tool: provar.automation.testrun ───────────────────────────────────────────
-export function registerAutomationTestRun(server) {
-    server.tool('provar.automation.testrun', [
-        'Trigger a LOCAL Provar automation test run using installed Provar binaries. Invokes `sf provar automation test run`.',
-        'PREREQUISITE: Run provar.automation.config.load first to register a provardx-properties.json — without this the command fails with MISSING_FILE.',
-        'Requires Provar to be installed locally and provarHome set correctly in the properties file.',
-        'Use provar.automation.setup first if Provar is not yet installed.',
-        'For grid/CI execution via Provar Quality Hub instead of running locally, use provar.qualityhub.testrun.',
-        'Typical local AI loop: config.load → compile → testrun → inspect results.',
-    ].join(' '), {
-        flags: z.array(z.string()).optional().default([]).describe('Raw CLI flags to forward (e.g. ["--project-path", "/path/to/project"])'),
-        sf_path: z.string().optional().describe('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")'),
+// ── Testrun output filter ─────────────────────────────────────────────────────
+const NOISE_PATTERNS = [/com\.networknt\.schema/, /SEVERE.*Failed to configure logger.*\.lck/];
+/**
+ * Strip Java schema-validator debug lines and stale logger-lock SEVERE warnings
+ * from Provar testrun output. These two patterns account for the bulk of output
+ * volume and cause MCP responses to be truncated before the pass/fail lines.
+ *
+ * Everything else (including real SEVERE failures) passes through unchanged.
+ * Collapses runs of blank lines to a single blank to keep the output readable.
+ * Returns the filtered text and the count of suppressed lines.
+ */
+export function filterTestRunOutput(raw) {
+    const lines = raw.split(/\r?\n/);
+    const kept = [];
+    let suppressed = 0;
+    let lastKeptWasBlank = false;
+    for (const rawLine of lines) {
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        if (NOISE_PATTERNS.some((p) => p.test(line))) {
+            suppressed++;
+            continue;
+        }
+        const isBlank = line.trim() === '';
+        if (isBlank && lastKeptWasBlank)
+            continue; // collapse blank runs
+        kept.push(line);
+        lastKeptWasBlank = isBlank;
+    }
+    let filtered = kept.join('\n');
+    if (suppressed > 0) {
+        filtered += `\n[testrun: ${suppressed} lines suppressed (schema validator / logger noise) — use provar_testrun_rca for full results]`;
+    }
+    return { filtered, suppressed };
+}
+// ── JUnit results enrichment ──────────────────────────────────────────────────
+// Overrideable in tests — bypasses the sf config file read
+let sfResultsPathOverride;
+/** Exposed for testing only — set the results path returned by the sf config reader. Pass undefined to reset. */
+export function setSfResultsPathForTesting(p) {
+    sfResultsPathOverride = p;
+}
+/**
+ * Resolves the actual results directory for the latest run.
+ * Provar's Increment disposition creates Results(1), Results(2)… as siblings of Results/.
+ * Returns the latest sibling dir, or the base path if no siblings exist.
+ */
+function resolveLatestResultsDir(resultsBase) {
+    const parent = path.dirname(resultsBase);
+    const base = path.basename(resultsBase);
+    try {
+        const safeName = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`^${safeName}\\((\\d+)\\)$`);
+        const indices = fs
+            .readdirSync(parent, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && pattern.test(e.name))
+            .map((e) => parseInt(pattern.exec(e.name)[1], 10));
+        if (indices.length > 0) {
+            const maxIdx = indices.reduce((a, b) => (a > b ? a : b), 0);
+            return path.join(parent, `${base}(${maxIdx})`);
+        }
+    }
+    catch {
+        // ignore filesystem errors
+    }
+    return resultsBase;
+}
+/**
+ * Reads resultsPath from the currently active provardx-properties.json (via ~/.sf/config.json),
+ * then resolves to the latest Increment-mode sibling directory.
+ * Returns null when the sf config or properties file cannot be read or is outside allowed paths.
+ */
+function readResultsPathFromSfConfig(config) {
+    if (sfResultsPathOverride !== undefined)
+        return sfResultsPathOverride;
+    try {
+        const sfConfigPath = path.join(os.homedir(), '.sf', 'config.json');
+        if (!fs.existsSync(sfConfigPath))
+            return null;
+        const sfConfig = JSON.parse(fs.readFileSync(sfConfigPath, 'utf-8'));
+        const propFilePath = sfConfig['PROVARDX_PROPERTIES_FILE_PATH'];
+        if (!propFilePath || !fs.existsSync(propFilePath))
+            return null;
+        // Guard: only read the properties file if it is within the session's allowed paths.
+        assertPathAllowed(propFilePath, config.allowedPaths);
+        const props = JSON.parse(fs.readFileSync(propFilePath, 'utf-8'));
+        const resultsBase = props['resultsPath'];
+        if (!resultsBase)
+            return null;
+        const resultsDir = resolveLatestResultsDir(resultsBase);
+        // Guard: only read the results directory if it is within the session's allowed paths.
+        assertPathAllowed(resultsDir, config.allowedPaths);
+        return resultsDir;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Tool: provar_automation_testrun ───────────────────────────────────────────
+export function registerAutomationTestRun(server, config) {
+    server.registerTool('provar_automation_testrun', {
+        title: 'Run Tests',
+        description: desc([
+            'Trigger a LOCAL Provar automation test run using installed Provar binaries. Invokes `sf provar automation test run`.',
+            'PREREQUISITE: Run provar_automation_config_load first to register a provardx-properties.json — without this the command fails with MISSING_FILE.',
+            'Requires Provar to be installed locally and provarHome set correctly in the properties file.',
+            'Use provar_automation_setup first if Provar is not yet installed.',
+            'For grid/CI execution via Provar Quality Hub instead of running locally, use provar_qualityhub_testrun.',
+            'Output buffer: a 50 MB maxBuffer is set so ENOBUFS on verbose Provar runs is now rare.',
+            'If ENOBUFS still occurs (extremely verbose logging), run `sf provar automation test run --json` directly in the terminal and pipe or tail the output instead of retrying this tool.',
+            'Typical local AI loop: config.load → compile → testrun → inspect results.',
+        ].join(' '), 'Run local Provar tests via sf CLI; requires config_load first.'),
+        inputSchema: {
+            flags: z
+                .array(z.string())
+                .optional()
+                .default([])
+                .describe(desc('Raw CLI flags to forward (e.g. ["--project-path", "/path/to/project"])', 'array, optional; raw CLI flags')),
+            sf_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")', 'string, optional; path to sf CLI')),
+        },
     }, ({ flags, sf_path }) => {
         const requestId = makeRequestId();
-        log('info', 'provar.automation.testrun', { requestId });
+        log('info', 'provar_automation_testrun', { requestId });
         try {
             const result = runSfCommand(['provar', 'automation', 'test', 'run', ...flags], sf_path);
-            const response = { requestId, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+            const { filtered, suppressed } = filterTestRunOutput(result.stdout);
+            // Attempt to enrich the response with structured step data from JUnit XML
+            const resultsPath = readResultsPathFromSfConfig(config);
+            const { steps, warning: junitWarning } = resultsPath
+                ? parseJUnitResults(resultsPath)
+                : { steps: [], warning: undefined };
             if (result.exitCode !== 0) {
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify(makeError('AUTOMATION_TESTRUN_FAILED', result.stderr || result.stdout, requestId)) }] };
+                const { filtered: filteredErr, suppressed: suppressedErr } = filterTestRunOutput(result.stderr || result.stdout);
+                const errBody = {
+                    ...makeError('AUTOMATION_TESTRUN_FAILED', filteredErr, requestId),
+                    ...(suppressedErr > 0 ? { output_lines_suppressed: suppressedErr } : {}),
+                };
+                if (steps.length > 0)
+                    errBody['steps'] = steps;
+                if (!resultsPath || junitWarning) {
+                    errBody['details'] = {
+                        warning: junitWarning ??
+                            'Could not locate results directory — step-level output unavailable. Run provar_automation_config_load first.',
+                    };
+                }
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(errBody) }] };
             }
+            const response = {
+                requestId,
+                exitCode: result.exitCode,
+                stdout: filtered,
+                stderr: result.stderr,
+            };
+            if (suppressed > 0)
+                response['output_lines_suppressed'] = suppressed;
+            if (steps.length > 0)
+                response['steps'] = steps;
+            if (junitWarning)
+                response['details'] = { warning: junitWarning };
             return { content: [{ type: 'text', text: JSON.stringify(response) }], structuredContent: response };
         }
         catch (err) {
-            return handleSpawnError(err, requestId, 'provar.automation.testrun');
+            return handleSpawnError(err, requestId, 'provar_automation_testrun');
         }
     });
 }
-// ── Tool: provar.automation.compile ───────────────────────────────────────────
+// ── Tool: provar_automation_compile ───────────────────────────────────────────
 export function registerAutomationCompile(server) {
-    server.tool('provar.automation.compile', [
-        'Compile a Provar automation project. Invokes `sf provar automation project compile`.',
-        'PREREQUISITE: Run provar.automation.config.load first to register a provardx-properties.json — without this the command fails with MISSING_FILE.',
-        'Run this before triggering a test run after modifying test cases.',
-    ].join(' '), {
-        flags: z.array(z.string()).optional().default([]).describe('Raw CLI flags to forward (e.g. ["--project-path", "/path/to/project"])'),
-        sf_path: z.string().optional().describe('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")'),
+    server.registerTool('provar_automation_compile', {
+        title: 'Compile Test Assets',
+        description: desc([
+            'Compile a Provar automation project. Invokes `sf provar automation project compile`.',
+            'PREREQUISITE: Run provar_automation_config_load first to register a provardx-properties.json — without this the command fails with MISSING_FILE.',
+            'Run this before triggering a test run after modifying test cases.',
+        ].join(' '), 'Compile a Provar project; requires config_load first.'),
+        inputSchema: {
+            flags: z
+                .array(z.string())
+                .optional()
+                .default([])
+                .describe(desc('Raw CLI flags to forward (e.g. ["--project-path", "/path/to/project"])', 'array, optional; raw CLI flags')),
+            sf_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")', 'string, optional; path to sf CLI')),
+        },
     }, ({ flags, sf_path }) => {
         const requestId = makeRequestId();
-        log('info', 'provar.automation.compile', { requestId });
+        log('info', 'provar_automation_compile', { requestId });
         try {
             const result = runSfCommand(['provar', 'automation', 'project', 'compile', ...flags], sf_path);
             const response = { requestId, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
             if (result.exitCode !== 0) {
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify(makeError('AUTOMATION_COMPILE_FAILED', result.stderr || result.stdout, requestId)) }] };
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(makeError('AUTOMATION_COMPILE_FAILED', result.stderr || result.stdout, requestId)),
+                        },
+                    ],
+                };
             }
             return { content: [{ type: 'text', text: JSON.stringify(response) }], structuredContent: response };
         }
         catch (err) {
-            return handleSpawnError(err, requestId, 'provar.automation.compile');
+            return handleSpawnError(err, requestId, 'provar_automation_compile');
         }
     });
 }
-// ── Tool: provar.automation.metadata.download ─────────────────────────────────
+// ── Tool: provar_automation_metadata_download ─────────────────────────────────
+const DOWNLOAD_ERROR_SUGGESTION = 'A [DOWNLOAD_ERROR] almost always means a Salesforce authentication failure for the connection being used. ' +
+    'Check: (1) the connection credentials in the Provar project .secrets file are current and not expired; ' +
+    '(2) the named connection exists in the project and the name is spelled correctly (case-sensitive); ' +
+    '(3) if using a scratch org, confirm it has not expired (`sf org list`); ' +
+    '(4) if testprojectSecrets is set in provardx-properties.json, it must be the encryption key string used to decrypt .secrets — not a file path.';
 export function registerAutomationMetadataDownload(server) {
-    server.tool('provar.automation.metadata.download', 'Download Salesforce metadata into a Provar project. Invokes `sf provar automation metadata download`.', {
-        flags: z.array(z.string()).optional().default([]).describe('Raw CLI flags to forward (e.g. ["--target-org", "myorg"])'),
-        sf_path: z.string().optional().describe('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")'),
+    server.registerTool('provar_automation_metadata_download', {
+        title: 'Download Salesforce Metadata',
+        description: desc([
+            'Download Salesforce metadata for one or more connections into a Provar project.',
+            'Invokes `sf provar automation metadata download`.',
+            'PREREQUISITE: Call provar_automation_config_load first — without it the command fails with MISSING_FILE.',
+            'Use the -c flag to specify connections: flags: ["-c", "ConnectionName1,ConnectionName2"].',
+            'Connection names are case-sensitive and must match the names defined in the Provar project.',
+            'If the download fails with [DOWNLOAD_ERROR], this is almost always a Salesforce authentication issue —',
+            'check that the credentials in the project .secrets file are current and that any referenced scratch orgs have not expired.',
+        ].join(' '), 'Download Salesforce metadata for project connections; requires config_load first.'),
+        inputSchema: {
+            flags: z
+                .array(z.string())
+                .optional()
+                .default([])
+                .describe(desc('Raw CLI flags to forward. Use ["-c", "Name1,Name2"] (or the equivalent --connections form) to target specific connections. Example: ["-c", "MyOrg,SandboxOrg"]', 'array, optional; raw CLI flags e.g. ["-c", "ConnName"]')),
+            sf_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")', 'string, optional; path to sf CLI')),
+        },
     }, ({ flags, sf_path }) => {
         const requestId = makeRequestId();
-        log('info', 'provar.automation.metadata.download', { requestId });
+        log('info', 'provar_automation_metadata_download', { requestId });
         try {
             const result = runSfCommand(['provar', 'automation', 'metadata', 'download', ...flags], sf_path);
-            const response = { requestId, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+            const message = result.stderr || result.stdout;
             if (result.exitCode !== 0) {
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify(makeError('AUTOMATION_METADATA_FAILED', result.stderr || result.stdout, requestId)) }] };
+                const isDownloadError = message.includes('[DOWNLOAD_ERROR]');
+                const details = isDownloadError
+                    ? { suggestion: DOWNLOAD_ERROR_SUGGESTION }
+                    : undefined;
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(makeError('AUTOMATION_METADATA_FAILED', message, requestId, false, details)),
+                        },
+                    ],
+                };
             }
+            const response = { requestId, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
             return { content: [{ type: 'text', text: JSON.stringify(response) }], structuredContent: response };
         }
         catch (err) {
-            return handleSpawnError(err, requestId, 'provar.automation.metadata.download');
+            return handleSpawnError(err, requestId, 'provar_automation_metadata_download');
         }
     });
 }
-// ── Tool: provar.automation.setup ─────────────────────────────────────────────
+// ── Tool: provar_automation_setup ─────────────────────────────────────────────
 /** Known system-level Provar install paths per platform. */
 const SYSTEM_INSTALL_BASES = {
-    win32: [
-        'C:/Program Files',
-        'C:/Program Files (x86)',
-    ],
-    darwin: [
-        '/Applications',
-    ],
-    linux: [
-        '/opt',
-        '/usr/local',
-    ],
+    win32: ['C:/Program Files', 'C:/Program Files (x86)'],
+    darwin: ['/Applications'],
+    linux: ['/opt', '/usr/local'],
 };
 /** Try to read a Provar version string from well-known files inside an install dir. */
 function readProvarVersion(installPath) {
@@ -299,22 +437,36 @@ function findExistingInstallations() {
     return found;
 }
 export function registerAutomationSetup(server) {
-    server.tool('provar.automation.setup', [
-        'Download and install Provar Automation binaries locally. Invokes `sf provar automation setup`.',
-        'Before downloading, checks for existing Provar installations in:',
-        '  • PROVAR_HOME environment variable',
-        '  • ./ProvarHome (default CLI install location)',
-        '  • C:\\Program Files\\Provar* (Windows system installs)',
-        '  • /Applications/Provar* (macOS app installs)',
-        'If an existing installation is found, returns its path so you can set provarHome in the properties file — skipping the download unless force is true.',
-        'After a successful install, update the provarHome property in provardx-properties.json to the returned install_path using provar.properties.set.',
-    ].join(' '), {
-        version: z.string().optional().describe('Specific Provar Automation version to install, e.g. "2.12.0". Omit to install the latest release.'),
-        force: z.boolean().optional().default(false).describe('Force a fresh download even if an existing installation is already detected (default: false).'),
-        sf_path: z.string().optional().describe('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")'),
+    server.registerTool('provar_automation_setup', {
+        title: 'Install Provar Automation',
+        description: desc([
+            'Download and install Provar Automation binaries locally. Invokes `sf provar automation setup`.',
+            'Before downloading, checks for existing Provar installations in:',
+            '  • PROVAR_HOME environment variable',
+            '  • ./ProvarHome (default CLI install location)',
+            '  • C:\\Program Files\\Provar* (Windows system installs)',
+            '  • /Applications/Provar* (macOS app installs)',
+            'If an existing installation is found, returns its path so you can set provarHome in the properties file — skipping the download unless force is true.',
+            'After a successful install, update the provarHome property in provardx-properties.json to the returned install_path using provar_properties_set.',
+        ].join(' '), 'Download and install Provar Automation binaries; skips if already installed.'),
+        inputSchema: {
+            version: z
+                .string()
+                .optional()
+                .describe(desc('Specific Provar Automation version to install, e.g. "2.12.0". Omit to install the latest release.', 'string, optional; version to install e.g. "2.12.0"')),
+            force: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe(desc('Force a fresh download even if an existing installation is already detected (default: false).', 'bool, optional; force re-download')),
+            sf_path: z
+                .string()
+                .optional()
+                .describe(desc('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")', 'string, optional; path to sf CLI')),
+        },
     }, ({ version, force, sf_path }) => {
         const requestId = makeRequestId();
-        log('info', 'provar.automation.setup', { requestId, version, force });
+        log('info', 'provar_automation_setup', { requestId, version, force });
         try {
             // ── 1. Check for existing installations ──────────────────────────────
             const existing = findExistingInstallations();
@@ -343,12 +495,17 @@ export function registerAutomationSetup(server) {
             if (result.exitCode !== 0) {
                 return {
                     isError: true,
-                    content: [{ type: 'text', text: JSON.stringify(makeError('AUTOMATION_SETUP_FAILED', result.stderr || result.stdout, requestId)) }],
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(makeError('AUTOMATION_SETUP_FAILED', result.stderr || result.stdout, requestId)),
+                        },
+                    ],
                 };
             }
             // ── 3. Locate the freshly installed ProvarHome ───────────────────────
             const freshInstalls = findExistingInstallations();
-            const localInstall = freshInstalls.find(i => i.source === 'local') ?? freshInstalls[0];
+            const localInstall = freshInstalls.find((i) => i.source === 'local') ?? freshInstalls[0];
             const installPath = localInstall?.path ?? path.resolve(process.cwd(), 'ProvarHome');
             const detectedVersion = localInstall?.version ?? version ?? null;
             const response = {
@@ -362,7 +519,7 @@ export function registerAutomationSetup(server) {
                 version: detectedVersion,
                 message: [
                     `Provar Automation installed successfully at: ${installPath}.`,
-                    'Update provarHome in your provardx-properties.json to this path using provar.properties.set.',
+                    'Update provarHome in your provardx-properties.json to this path using provar_properties_set.',
                 ].join(' '),
             };
             return {
@@ -371,15 +528,15 @@ export function registerAutomationSetup(server) {
             };
         }
         catch (err) {
-            return handleSpawnError(err, requestId, 'provar.automation.setup');
+            return handleSpawnError(err, requestId, 'provar_automation_setup');
         }
     });
 }
 // ── Bulk registration ─────────────────────────────────────────────────────────
-export function registerAllAutomationTools(server) {
+export function registerAllAutomationTools(server, config) {
     registerAutomationSetup(server);
-    registerAutomationConfigLoad(server);
-    registerAutomationTestRun(server);
+    registerAutomationConfigLoad(server, config);
+    registerAutomationTestRun(server, config);
     registerAutomationCompile(server);
     registerAutomationMetadataDownload(server);
 }