@provartesting/provardx-cli 1.5.0-dev.1 → 1.5.0

package/lib/mcp/tools/sfSpawn.js

@@ -4,6 +4,9 @@
  * 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 fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { spawnSync as _spawnSync } from 'node:child_process';
 /**
  * Thin wrapper around spawnSync so tests can stub sfSpawnHelper.spawnSync.
@@ -15,21 +18,166 @@ export const sfSpawnHelper = {
 // ── Shared error type ─────────────────────────────────────────────────────────
 export class SfNotFoundError extends Error {
     code = 'SF_NOT_FOUND';
-    constructor() {
-        super('sf CLI not found in PATH. Install Salesforce CLI (`npm install -g @salesforce/cli`) and ensure it is in your PATH.');
+    constructor(sfPath) {
+        const where = sfPath ? `at explicit path "${sfPath}"` : 'in PATH or common npm/nvm/volta 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").');
         this.name = 'SfNotFoundError';
     }
 }
+const MAX_BUFFER = 50 * 1024 * 1024; // 50 MB — prevents ENOBUFS on verbose Provar runs
+// ── SF CLI discovery ──────────────────────────────────────────────────────────
+/**
+ * Returns candidate sf CLI paths in common 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'),
+            // Windows standalone installer (https://developer.salesforce.com/tools/salesforcecli)
+            path.join('C:', 'Program Files', 'sf', 'bin', 'sf.cmd'),
+            path.join('C:', 'Program Files', 'sf', 'client', 'bin', '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;
+}
+// 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.
+ * Pass `undefined` to reset the cache so the next call triggers a fresh probe.
+ */
+export function setSfPathCacheForTesting(value) {
+    cachedSfPath = value;
+}
+// Platform override used in tests so Windows-specific shell logic can be exercised on any OS.
+let sfPlatformOverride;
+/** Exposed for testing only — overrides process.platform for needsWindowsShell decisions. */
+export function setSfPlatformForTesting(platform) {
+    sfPlatformOverride = platform;
+}
+/**
+ * Returns true when spawning `executable` requires the Windows shell.
+ * On Windows, `.cmd` and `.bat` batch scripts cannot be executed directly by
+ * Node's spawnSync — they must be invoked through cmd.exe (i.e. shell: true).
+ * The bare name "sf" also needs this treatment on Windows because the file on
+ * disk is actually "sf.cmd" and Node won't auto-append the extension.
+ */
+export function needsWindowsShell(executable, platform = process.platform) {
+    if (platform !== 'win32')
+        return false;
+    const lower = executable.toLowerCase();
+    return lower.endsWith('.cmd') || lower.endsWith('.bat') || !path.extname(lower);
+}
+function resolveSfExecutable() {
+    if (cachedSfPath !== undefined)
+        return cachedSfPath;
+    const platform = sfPlatformOverride ?? process.platform;
+    // Two-phase probe avoids false-positives on Windows with shell:true.
+    // When shell:true is used, cmd.exe spawns successfully even when `sf` is
+    // missing — it exits non-zero with "not recognised" in stderr but sets no
+    // probe.error. Trying shell:false first catches both cases correctly.
+    //
+    // First attempt: shell:false (works on Linux/macOS; gives ENOENT on Windows if
+    // sf.cmd is on PATH but requires the shell).
+    const probe = sfSpawnHelper.spawnSync('sf', ['--version'], {
+        encoding: 'utf-8',
+        shell: false,
+        maxBuffer: 1024 * 1024,
+    });
+    if (!probe.error && probe.status === 0) {
+        cachedSfPath = 'sf';
+        return cachedSfPath;
+    }
+    // Windows fallback: retry with shell:true when the plain probe failed
+    // with ENOENT — meaning sf.cmd exists on PATH but can't run without the shell.
+    if (platform === 'win32' && probe.error?.code === 'ENOENT') {
+        const probeShell = sfSpawnHelper.spawnSync('sf', ['--version'], {
+            encoding: 'utf-8',
+            shell: true,
+            maxBuffer: 1024 * 1024,
+        });
+        if (!probeShell.error && probeShell.status === 0) {
+            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;
+}
+/**
+ * Reject shell metacharacters in an sf_path that will be executed via shell:true.
+ * On Windows, cmd.exe interprets & | ; < > ` ' " and newlines as shell syntax.
+ * A valid filesystem path should never contain these characters.
+ */
+function assertShellSafePath(sfPath) {
+    if (/[&|;<>`'"\n\r]/.test(sfPath)) {
+        throw Object.assign(new Error('sf_path contains characters that are unsafe for shell execution on Windows ' +
+            '(& | ; < > ` \' " or line-breaks). Provide an absolute filesystem path to the sf executable.'), { code: 'INVALID_SF_PATH' });
+    }
+}
 /**
  * Run `sf <args>` synchronously and return stdout, stderr, and exit code.
- * Throws SfNotFoundError if the `sf` binary is not in PATH.
+ * Throws SfNotFoundError if the `sf` binary cannot be found.
+ * Pass `sfPath` to override auto-discovery with an explicit executable path.
  */
-export function runSfCommand(args) {
-    const result = sfSpawnHelper.spawnSync('sf', args, { encoding: 'utf-8', shell: false });
+export function runSfCommand(args, sfPath) {
+    // Treat empty/whitespace sfPath as absent so auto-discovery runs instead of
+    // throwing SfNotFoundError with no useful path hint.
+    const trimmedSfPath = sfPath?.trim();
+    const resolvedSfPath = trimmedSfPath !== '' ? trimmedSfPath : undefined;
+    const executable = resolvedSfPath ?? resolveSfExecutable();
+    if (!executable)
+        throw new SfNotFoundError();
+    const platform = sfPlatformOverride ?? process.platform;
+    const useShell = needsWindowsShell(executable, platform);
+    // Guard against injection when shell:true is used with a user-supplied path.
+    // Common install locations returned by resolveSfExecutable() are safe by construction.
+    if (useShell && resolvedSfPath) {
+        assertShellSafePath(resolvedSfPath);
+    }
+    const result = sfSpawnHelper.spawnSync(executable, args, {
+        encoding: 'utf-8',
+        shell: useShell,
+        maxBuffer: MAX_BUFFER,
+    });
     if (result.error) {
         const err = result.error;
         if (err.code === 'ENOENT') {
-            throw new SfNotFoundError();
+            throw new SfNotFoundError(resolvedSfPath);
         }
         throw result.error;
     }

package/lib/mcp/tools/sfSpawn.js.map

@@ -1 +1 @@
-{"version":3,"file":"sfSpawn.js","sourceRoot":"","sources":["../../../src/mcp/tools/sfSpawn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,SAAS,EAAE,UAAU;CACtB,CAAC;AAEF,iFAAiF;AAEjF,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxB,IAAI,GAAG,cAAc,CAAC;IACtC;QACE,KAAK,CACH,oHAAoH,CACrH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAUD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAExF,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,MAAM,CAAC,KAA8B,CAAC;QAClD,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,eAAe,EAAE,CAAC;QAC9B,CAAC;QACD,MAAM,MAAM,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;QAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC;KAC7B,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"sfSpawn.js","sourceRoot":"","sources":["../../../src/mcp/tools/sfSpawn.ts"],"names":[],"mappings":"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"}

package/lib/mcp/tools/testCaseGenerate.js

@@ -54,6 +54,14 @@ function buildStepWarnings(steps) {
             'To assert SOQL results use either: (a) a ForEach loop over the result list with AssertValues inside, ' +
             'or (b) a SetValues step to extract a specific field into a named variable, then assert that variable.');
     }
+    // D7: Cleanup steps placed after a potential failure point are skipped when stopOnError=false.
+    if (resolvedIds.includes(SHORTHAND_TO_FQID['ApexDeleteObject'] ?? '')) {
+        warnings.push('ApexDeleteObject detected (likely cleanup): with stopOnError=false Provar skips all steps after ' +
+            'the first failure, so cleanup steps placed at the end of the test will NOT run when an earlier ' +
+            'step fails — leaving orphaned records in the org. ' +
+            'Wrap cleanup in a Provar TearDown callable, or place create/delete inside the same UiWithScreen ' +
+            'clause so both run as a unit regardless of failure.');
+    }
     return warnings;
 }
 // ── Schema ────────────────────────────────────────────────────────────────────
@@ -69,58 +77,92 @@ const StepSchema = z.object({
     attributes: z
         .record(z.string())
         .default({})
-        .describe('Step argument values as key/value pairs. Written as <arguments><argument id="key"><value .../></argument></arguments> ' +
-        'inside the <apiCall> element — the format Provar runtime requires. ' +
+        .describe('Step argument values as key/value pairs. Written as <arguments><argument id="key"><value .../></argument></arguments>. ' +
         'Do NOT rely on XML attributes on <apiCall>; the runtime silently ignores them. ' +
-        'Example: { "connectionName": "MyOrg", "objectApiName": "Opportunity" }'),
+        'Special value conventions (applied automatically by the generator): ' +
+        '(1) Variable references: wrap the name in braces, e.g. "{MyVar}" → emitted as class="variable" <path element="MyVar"/>. ' +
+        '    Dotted paths are also supported: "{Obj.Field}" → two <path> elements. ' +
+        '(2) SetValues: pass each variable name and its value as a flat key/value pair; ' +
+        '    the generator wraps them in <value class="valueList"><namedValues>...</namedValues></value> automatically. ' +
+        '    Example: { "testCaseName": "TC_New", "testType": "Acceptance testing" } ' +
+        '(3) AssertValues: pass assertion arguments as flat key/value pairs; emitted as flat <argument> elements, NOT wrapped in valueList/namedValues. ' +
+        '(4) target argument (UiWithScreen / UiWithRow): pass the sf:ui:target or ui:pageobject:target URI; ' +
+        '    emitted as class="uiTarget" uri="...". ' +
+        '(5) locator argument (UiDoAction / UiAssert): pass the locator URI; emitted as class="uiLocator" uri="...". ' +
+        'All other string values use class="value" valueClass="string".'),
 });
 const TOOL_DESCRIPTION = [
     'Generate a Provar XML test case skeleton with proper UUID v4 guids, sequential testItemId values, and <steps> structure.',
     'Returns XML content. Writes to disk only when dry_run=false.',
+    'Generated structure: <?xml version="1.0" encoding="UTF-8" standalone="no"?> with <testCase guid="..." id="1" registryId="..."> (id is always the integer literal "1" as required by the Provar runtime), a <summary/> child, then <steps>.',
+    'URI-aware generation: use target_uri to control the XML nesting structure.',
+    '  - sf:ui:target (or omit target_uri) → flat Salesforce XML structure (existing behaviour).',
+    '  - ui:pageobject:target?pageId=pageobjects.PageClass → wraps all steps in a UiWithScreen element targeting that non-SF page object.',
     'API IDs: shorthand forms (e.g. UiConnect, ApexSoqlQuery) are automatically expanded to fully-qualified IDs required by the Provar runtime.',
     'Step arguments: attributes are emitted as <arguments><argument id="..."><value .../></argument></arguments> — the only format the Provar runtime processes.',
     'Shorthand XML attributes on <apiCall> are silently ignored at runtime; always supply arguments via the attributes map.',
+    'ApexSoqlQuery argument IDs: soqlQuery (the SOQL SELECT statement), resultListName (binds result list to a variable), apexConnectionName (named connection), resultScope (optional).',
     'Data-driven note: <dataTable> only iterates rows when the test case runs via a test plan instance (.testinstance).',
     'Running directly via the provardx testCase property resolves all data table variables as null.',
-    'Use provar.testplan.add-instance to wire into a plan for data-driven execution.',
+    'Use provar_testplan_add-instance to wire into a plan for data-driven execution.',
     'ApexReadObject requires field names in attributes; omitting them produces MALFORMED_QUERY. Prefer ApexSoqlQuery.',
     'AssertValues on SOQL results: index paths like "ResultList[0].Field" are not supported.',
     'Use ForEach to iterate the result list, or SetValues to extract a field into a variable first.',
-    'Validation: the response always includes a validation field with is_valid, validity_score, quality_score, and any structural issues — check this before attempting to run the test case.',
+    'SetValues: pass named variable values as flat key/value pairs in attributes; ' +
+        'the generator wraps them in <value class="valueList"><namedValues>...</namedValues></value> automatically.',
+    'AssertValues: pass assertion values as flat key/value argument pairs; emitted as flat arguments, NOT wrapped in namedValues. ' +
+        'If AssertValues uses namedValues-shaped content, validation reports warning ASSERT-001.',
+    'Variable references: pass values as "{VarName}" (braces); emitted as class="variable" <path element="VarName"/>.',
+    'target argument (UiWithScreen/UiWithRow): pass the URI value; emitted as class="uiTarget" uri="...".',
+    'locator argument (UiDoAction/UiAssert): pass the URI value; emitted as class="uiLocator" uri="...".',
+    'Edit page objects: action=Edit targets require a compiled page object for the SF object. ' +
+        'If none exists in the project page-objects directory, the locator binding will fail at runtime. ' +
+        'For objects without a compiled Edit page object, use inline edit instead: sfIleActivate to activate the field, ' +
+        'set the value, then SaveEdit binding on the Record view screen.',
+    'Provar IDE warning: opening a generated test case in Provar IDE injects empty <argument id="..."/> elements for known parameter IDs. ' +
+        'If the empty element appears after a populated one, the empty version wins at runtime. ' +
+        'Always check for and remove duplicate empty arguments after any IDE open/save cycle before re-running.',
+    'Cleanup warning: ApexDeleteObject steps near end of test will be skipped if an earlier step fails (stopOnError=false). Use a TearDown callable.',
+    'Validation: when validate_after_edit=true (default) the response includes a validation field and returns TESTCASE_INVALID if the generated XML fails structural checks.',
+    'Grounding: call provar_qualityhub_examples_retrieve before generating to get corpus examples for the scenario — correct XML structure for the step types you need.',
+    'If the response has count: 0 with a warning field (API unavailable or not configured), fall back: read the provar://docs/step-reference MCP resource for step types and attribute formats, then continue.',
 ].join(' ');
 export function registerTestCaseGenerate(server, config) {
-    server.tool('provar.testcase.generate', TOOL_DESCRIPTION, {
-        test_case_name: z.string().describe('Test case name (human-readable label)'),
-        test_case_id: z
-            .string()
-            .optional()
-            .describe('Explicit test case id; auto-generated UUID v4 if omitted'),
-        steps: z.array(StepSchema).default([]).describe('Ordered list of test steps'),
-        output_path: z
-            .string()
-            .optional()
-            .describe('Suggested file path for the .xml file (returned in response)'),
-        overwrite: z.boolean().default(false).describe('Overwrite if output_path file already exists'),
-        dry_run: z
-            .boolean()
-            .default(true)
-            .describe('true = return XML only (default); false = write to output_path'),
-        idempotency_key: z
-            .string()
-            .optional()
-            .describe('Caller-provided key echoed back for deduplication tracking'),
+    server.registerTool('provar_testcase_generate', {
+        title: 'Generate Test Case',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            test_case_name: z.string().describe('Test case name (human-readable label)'),
+            steps: z.array(StepSchema).default([]).describe('Ordered list of test steps'),
+            target_uri: z
+                .string()
+                .optional()
+                .describe('Page object URI that determines the XML nesting structure. ' +
+                'Omit or use "sf:ui:target" for Salesforce targets (flat structure). ' +
+                'Use "ui:pageobject:target?pageId=pageobjects.PageClass" for non-SF page objects — ' +
+                'steps are wrapped in a UiWithScreen element targeting that class.'),
+            output_path: z.string().optional().describe('Suggested file path for the .xml file (returned in response)'),
+            overwrite: z.boolean().default(false).describe('Overwrite if output_path file already exists'),
+            dry_run: z.boolean().default(true).describe('true = return XML only (default); false = write to output_path'),
+            validate_after_edit: z
+                .boolean()
+                .default(true)
+                .describe('Run structural validation after generation (default: true). ' +
+                'Returns TESTCASE_INVALID error if the generated XML fails validation. ' +
+                'Set false to skip validation and omit the validation field from the response.'),
+            idempotency_key: z.string().optional().describe('Caller-provided key echoed back for deduplication tracking'),
+        },
     }, (input) => {
         const requestId = makeRequestId();
-        log('info', 'provar.testcase.generate', {
+        log('info', 'provar_testcase_generate', {
             requestId,
             test_case_name: input.test_case_name,
             dry_run: input.dry_run,
+            target_uri: input.target_uri,
         });
         try {
             const xmlContent = buildTestCaseXml(input);
-            const filePath = input.output_path
-                ? path.resolve(input.output_path)
-                : undefined;
+            const filePath = input.output_path ? path.resolve(input.output_path) : undefined;
             let written = false;
             if (filePath && !input.dry_run) {
                 assertPathAllowed(filePath, config.allowedPaths);
@@ -131,19 +173,11 @@ export function registerTestCaseGenerate(server, config) {
                 fs.mkdirSync(path.dirname(filePath), { recursive: true });
                 fs.writeFileSync(filePath, xmlContent, 'utf-8');
                 written = true;
-                log('info', 'provar.testcase.generate: wrote file', { requestId, filePath });
+                log('info', 'provar_testcase_generate: wrote file', { requestId, filePath });
             }
             const warnings = buildStepWarnings(input.steps);
-            const validationFull = validateTestCase(xmlContent, input.test_case_name);
-            const validationSlim = {
-                is_valid: validationFull.is_valid,
-                validity_score: validationFull.validity_score,
-                quality_score: validationFull.quality_score,
-                error_count: validationFull.error_count,
-                warning_count: validationFull.warning_count,
-                issues: validationFull.issues,
-            };
-            const result = {
+            const runValidation = input.validate_after_edit !== false;
+            const baseResult = {
                 requestId,
                 xml_content: xmlContent,
                 file_path: filePath,
@@ -151,71 +185,185 @@ export function registerTestCaseGenerate(server, config) {
                 dry_run: input.dry_run,
                 step_count: input.steps.length,
                 idempotency_key: input.idempotency_key,
-                validation: validationSlim,
                 ...(warnings.length > 0 ? { warnings } : {}),
             };
+            if (runValidation) {
+                const validationFull = validateTestCase(xmlContent, input.test_case_name);
+                const validationSlim = {
+                    is_valid: validationFull.is_valid,
+                    validity_score: validationFull.validity_score,
+                    quality_score: validationFull.quality_score,
+                    error_count: validationFull.error_count,
+                    warning_count: validationFull.warning_count,
+                    issues: validationFull.issues,
+                };
+                if (!validationFull.is_valid) {
+                    const errResult = makeError('TESTCASE_INVALID', `Generated test case failed structural validation (${validationFull.error_count} error(s)). See details.validation.`, requestId, false, { validation: validationSlim });
+                    log('warn', 'provar_testcase_generate: TESTCASE_INVALID', { requestId });
+                    return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
+                }
+                const result = { ...baseResult, validation: validationSlim };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result) }],
+                    structuredContent: result,
+                };
+            }
             return {
-                content: [{ type: 'text', text: JSON.stringify(result) }],
-                structuredContent: result,
+                content: [{ type: 'text', text: JSON.stringify(baseResult) }],
+                structuredContent: baseResult,
             };
         }
         catch (err) {
             const error = err;
-            const errResult = makeError(error instanceof PathPolicyError ? error.code : (error.code ?? 'GENERATE_ERROR'), error.message, requestId, false);
-            log('error', 'provar.testcase.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_testcase_generate failed', { requestId, error: error.message });
             return { isError: true, content: [{ type: 'text', text: JSON.stringify(errResult) }] };
         }
     });
 }
 // ── XML builder ───────────────────────────────────────────────────────────────
-function buildArgumentsXml(attributes) {
+// F1/F3: build class="compound" for strings that mix literal text with {VarName} tokens.
+function buildCompoundValue(val, indent) {
+    const i = `${indent}  `;
+    const parts = [];
+    const tokenRe = /\{([\w.]+)\}/g;
+    let last = 0;
+    let m;
+    while ((m = tokenRe.exec(val)) !== null) {
+        const before = val.slice(last, m.index);
+        if (before)
+            parts.push(`${i}<value valueClass="string">${escapeXmlContent(before)}</value>`);
+        const pathElements = m[1]
+            .split('.')
+            .map((p) => `${i}  <path element="${escapeXmlAttr(p)}"/>`)
+            .join('\n');
+        parts.push(`${i}<variable>\n${pathElements}\n${i}</variable>`);
+        last = m.index + m[0].length;
+    }
+    const tail = val.slice(last);
+    if (tail)
+        parts.push(`${i}<value valueClass="string">${escapeXmlContent(tail)}</value>`);
+    return `${indent}<value class="compound">\n${i}<parts>\n${parts.join('\n')}\n${i}</parts>\n${indent}</value>`;
+}
+// Build the <value> element for a single argument (D2/D4/F1 aware).
+// inNamedValues: when true (inside SetValues namedValues), skip uiTarget/uiLocator dispatch.
+// apiId: resolved API ID used to restrict key-name dispatch to the correct UI APIs.
+function buildArgumentValue(key, val, indent, inNamedValues = false, apiId = '') {
+    // D4: {VarName} or {Obj.Field} → class="variable" with <path> elements.
+    const varMatch = /^\{([\w.]+)\}$/.exec(val);
+    if (varMatch) {
+        const pathElements = varMatch[1]
+            .split('.')
+            .map((p) => `${indent}  <path element="${escapeXmlAttr(p)}"/>`)
+            .join('\n');
+        return `${indent}<value class="variable">\n${pathElements}\n${indent}</value>`;
+    }
+    // F1/F3: {VarName} embedded in surrounding text → class="compound" with <parts>.
+    if (/\{[\w.]+\}/.test(val)) {
+        return buildCompoundValue(val, indent);
+    }
+    if (!inNamedValues) {
+        // D2: 'target' argument → class="uiTarget" (only for UiWithScreen / UiWithRow).
+        if (key === 'target' && (apiId.includes('UiWithScreen') || apiId.includes('UiWithRow'))) {
+            return `${indent}<value class="uiTarget" uri="${escapeXmlAttr(val)}"/>`;
+        }
+        // D2: 'locator' argument → class="uiLocator" (only for UiDoAction / UiAssert).
+        if (key === 'locator' && (apiId.includes('UiDoAction') || apiId.includes('UiAssert'))) {
+            return `${indent}<value class="uiLocator" uri="${escapeXmlAttr(val)}"/>`;
+        }
+    }
+    return `${indent}<value class="value" valueClass="string">${escapeXmlContent(val)}</value>`;
+}
+function buildArgumentsXml(attributes, baseIndent = '      ', apiId = '') {
     const entries = Object.entries(attributes);
     if (entries.length === 0)
         return '';
     const argLines = entries
-        .map(([k, v]) => `      <argument id="${escapeXmlAttr(k)}">\n` +
-        `        <value class="value" valueClass="String">${escapeXmlContent(v)}</value>\n` +
-        '      </argument>')
+        .map(([k, v]) => {
+        const valueXml = buildArgumentValue(k, v, `${baseIndent}  `, false, apiId);
+        return `${baseIndent}<argument id="${escapeXmlAttr(k)}">\n` + valueXml + '\n' + `${baseIndent}</argument>`;
+    })
         .join('\n');
-    return `\n      <arguments>\n${argLines}\n      </arguments>\n    `;
+    return `\n${baseIndent}<arguments>\n${argLines}\n${baseIndent}</arguments>\n${baseIndent.slice(0, -2)}`;
+}
+// D3: SetValues — all attributes become <namedValues> under a single 'values' argument.
+function buildSetValuesXml(attributes, baseIndent) {
+    const entries = Object.entries(attributes);
+    if (entries.length === 0)
+        return '';
+    const i = (n) => baseIndent + '  '.repeat(n);
+    const namedValueLines = entries
+        .map(([name, val]) => {
+        const valueXml = buildArgumentValue(name, val, `${i(3)}  `, true);
+        return `${i(3)}<namedValue name="${escapeXmlAttr(name)}">\n${valueXml}\n${i(3)}</namedValue>`;
+    })
+        .join('\n');
+    return (`\n${i(0)}<arguments>\n` +
+        `${i(0)}<argument id="values">\n` +
+        `${i(1)}<value class="valueList" mutable="Mutable">\n` +
+        `${i(2)}<namedValues>\n` +
+        namedValueLines +
+        '\n' +
+        `${i(2)}</namedValues>\n` +
+        `${i(1)}</value>\n` +
+        `${i(0)}</argument>\n` +
+        `${i(0)}</arguments>\n` +
+        `${baseIndent.slice(0, -2)}`);
+}
+function buildFlatStepXml(step, testItemId, indent) {
+    const guid = randomUUID();
+    const resolvedApiId = resolveApiId(step.api_id);
+    const baseIndent = indent + '  ';
+    // Use SetValues structure for any SetValues API (string-match mirrors the validator).
+    const argumentsXml = resolvedApiId.includes('SetValues')
+        ? buildSetValuesXml(step.attributes, baseIndent)
+        : buildArgumentsXml(step.attributes, baseIndent, resolvedApiId);
+    if (argumentsXml) {
+        return (`${indent}<apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}"` +
+            ` name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}">${argumentsXml}</apiCall>`);
+    }
+    return (`${indent}<apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}"` +
+        ` name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}"/>`);
 }
 function buildTestCaseXml(input) {
-    const testCaseId = input.test_case_id ?? randomUUID();
     const testCaseGuid = randomUUID();
     const registryId = randomUUID();
-    const stepLines = input.steps
-        .map((step, i) => {
-        const guid = randomUUID();
-        const testItemId = i + 1;
-        const resolvedApiId = resolveApiId(step.api_id);
-        const argumentsXml = buildArgumentsXml(step.attributes);
-        if (argumentsXml) {
-            return (`    <apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}"` +
-                ` name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}">${argumentsXml}</apiCall>`);
-        }
-        return (`    <apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}"` +
-            ` name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}"/>`);
-    })
-        .join('\n');
-    return ('<?xml version="1.0" encoding="UTF-8"?>\n' +
-        `<testCase id="${testCaseId}" guid="${testCaseGuid}" registryId="${registryId}"` +
-        ` name="${escapeXmlAttr(input.test_case_name)}">\n` +
+    let stepLines;
+    const isNonSf = !!input.target_uri && input.target_uri.startsWith('ui:');
+    if (isNonSf && input.target_uri) {
+        stepLines = buildUiWithScreenXml(input.steps, input.target_uri);
+    }
+    else {
+        const lines = input.steps.map((step, i) => buildFlatStepXml(step, i + 1, '    ')).join('\n');
+        stepLines = lines || '    <!-- TODO: Add test steps here -->';
+    }
+    // Provar requires: standalone="no", id="1" (integer literal), no name attr, <summary/> before <steps>.
+    return ('<?xml version="1.0" encoding="UTF-8" standalone="no"?>\n' +
+        `<testCase guid="${testCaseGuid}" id="1" registryId="${registryId}">\n` +
+        '  <summary/>\n' +
         '  <steps>\n' +
-        (stepLines || '    <!-- TODO: Add test steps here -->') +
+        stepLines +
         '\n  </steps>\n' +
         '</testCase>\n');
 }
+function buildUiWithScreenXml(steps, targetUri) {
+    const wrapperGuid = randomUUID();
+    const wrapperApiId = resolveApiId('UiWithScreen');
+    // Inner steps use testItemIds starting at 3; the substeps clause itself occupies testItemId=2
+    const innerLines = steps.map((step, i) => buildFlatStepXml(step, i + 3, '            ')).join('\n');
+    const stepsContent = innerLines ? `\n${innerLines}\n          ` : '';
+    const clausesXml = '\n      <clauses>\n' +
+        '        <clause name="substeps" testItemId="2">\n' +
+        `          <steps>${stepsContent}</steps>\n` +
+        '        </clause>\n' +
+        '      </clauses>\n    ';
+    return (`    <apiCall guid="${wrapperGuid}" apiId="${wrapperApiId}"` +
+        ` name="With page" testItemId="1">${buildArgumentsXml({ target: targetUri }, '      ', wrapperApiId).trimEnd()}${clausesXml}</apiCall>`);
+}
 function escapeXmlAttr(value) {
-    return value
-        .replace(/&/g, '&amp;')
-        .replace(/"/g, '&quot;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 function escapeXmlContent(value) {
-    return value
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 //# sourceMappingURL=testCaseGenerate.js.map