@provartesting/provardx-cli 1.5.3 → 1.6.1

package/lib/mcp/tools/sfSpawn.js

@@ -27,7 +27,50 @@ export class SfNotFoundError extends Error {
         this.name = 'SfNotFoundError';
     }
 }
-const MAX_BUFFER = 50 * 1024 * 1024; // 50 MB — prevents ENOBUFS on verbose Provar runs
+/** Remediation command for a missing Provar sf plugin. */
+export const PROVAR_PLUGIN_INSTALL_HINT = 'sf plugins install @provartesting/provardx-cli';
+/**
+ * Raised when the `sf` binary is present but the `@provartesting/provardx-cli`
+ * plugin is not installed (the `sf` CLI has no `provar` topic). Mirrors
+ * SfNotFoundError so callers get a dedicated code + actionable remediation
+ * instead of an opaque `AUTOMATION_*_FAILED` carrying "Command provar not found".
+ */
+export class ProvarPluginNotFoundError extends Error {
+    code = 'PROVAR_PLUGIN_NOT_FOUND';
+    constructor() {
+        super('The Provar sf plugin is not installed — the sf CLI has no "provar" topic. ' +
+            `Install it with: ${PROVAR_PLUGIN_INSTALL_HINT}`);
+        this.name = 'ProvarPluginNotFoundError';
+    }
+}
+// Patterns sf emits when the `provar` topic/command is unknown (plugin missing).
+const PROVAR_PLUGIN_MISSING_PATTERNS = [
+    /command\s+provar\S*\s+not\s+found/i, // "command provar not found" / "command provar:automation:... not found"
+    /\bprovar\S*\s+is not a[n]?\s+(?:sf|@salesforce\/cli)\s+command/i, // oclif "provar is not a sf command"
+    /no such (?:command|topic)[^\n]*\bprovar\b/i,
+];
+/**
+ * Heuristic: does sf stdout/stderr indicate the `provar` topic/plugin is missing?
+ * Used to translate a generic non-zero sf exit into PROVAR_PLUGIN_NOT_FOUND.
+ */
+export function isProvarPluginMissing(stdout, stderr) {
+    const haystack = `${stderr ?? ''}\n${stdout ?? ''}`;
+    return PROVAR_PLUGIN_MISSING_PATTERNS.some((re) => re.test(haystack));
+}
+/**
+ * Lightweight probe for the `provar` topic. Returns true when `sf provar --help`
+ * succeeds (plugin installed), false when sf is missing or the topic is absent.
+ * Non-throwing so it can be used as a best-effort startup health check.
+ */
+export function probeProvarTopic(sfPath) {
+    try {
+        const result = runSfCommand(['provar', '--help'], sfPath);
+        return result.exitCode === 0 && !isProvarPluginMissing(result.stdout, result.stderr);
+    }
+    catch {
+        return false;
+    }
+}
 // ── SF CLI discovery ──────────────────────────────────────────────────────────
 /**
  * Returns candidate sf CLI paths in common install locations.
@@ -149,6 +192,22 @@ function assertShellSafePath(sfPath) {
             '(& | ; < > ` \' " or line-breaks). Provide an absolute filesystem path to the sf executable.'), { code: 'INVALID_SF_PATH' });
     }
 }
+/**
+ * Quote a single command-line token for cmd.exe when the whole command is run
+ * through `shell: true`. Tokens containing whitespace or cmd-significant
+ * characters are wrapped in double quotes (embedded `"` doubled per cmd rules);
+ * simple tokens are left as-is. This is what keeps spaced paths — e.g.
+ * `C:\Program Files\sf\client\bin\sf.cmd` or a `--properties-file` value under a
+ * "Provar Manager" directory — from being split by cmd.exe.
+ */
+function quoteWindowsToken(token) {
+    if (token === '')
+        return '""';
+    if (/[\s"&|<>^()]/.test(token)) {
+        return `"${token.replace(/"/g, '""')}"`;
+    }
+    return token;
+}
 /**
  * Run `sf <args>` synchronously and return stdout, stderr, and exit code.
  * Throws SfNotFoundError if the `sf` binary cannot be found.
@@ -169,23 +228,119 @@ export function runSfCommand(args, sfPath) {
     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(resolvedSfPath);
+    // On Windows, `.cmd`/`.bat`/bare-name executables must run through cmd.exe
+    // (shell:true). Under shell:true Node concatenates executable + args into one
+    // unquoted string, so spaces in the auto-resolved Program Files path, an
+    // explicit sf_path, or any argument value would split the command
+    // (`'C:\Program' is not recognized ...`). Pre-quote the executable and each
+    // argument: Node joins them and wraps the whole line in cmd's outer quotes,
+    // and cmd's `/s` rule strips only that outermost pair, preserving our
+    // per-token quoting. This applies to auto-resolved paths too — not just
+    // user-supplied ones. On non-Windows the args pass through verbatim.
+    const spawnExecutable = useShell ? quoteWindowsToken(executable) : executable;
+    const spawnArgs = useShell ? args.map(quoteWindowsToken) : args;
+    return captureSpawnToFiles(spawnExecutable, spawnArgs, useShell, resolvedSfPath);
+}
+/**
+ * Run spawnSync capturing the child's stdout/stderr to temp files instead of an
+ * in-memory pipe, then read them back after the child exits.
+ *
+ * spawnSync's `maxBuffer` buffers all child output in RAM and aborts the whole
+ * call with `ENOBUFS` the moment that ceiling is crossed — a verbose Provar run
+ * (e.g. testOutputLevel DETAILED) routinely overflowed even a 50 MB cap and lost
+ * the run. Streaming straight to file descriptors removes the in-memory ceiling
+ * during capture, so `maxBuffer`-induced ENOBUFS is structurally impossible.
+ * Because the child writes directly to a file descriptor there is also no pipe to
+ * fill, which avoids the OS-level `ENOBUFS` seen on Windows under `shell: true`.
+ *
+ * (The captured output is still read back into a string after the child exits, so
+ * an extreme multi-hundred-MB run can hit Node's max string length — far above the
+ * 50 MB pipe boundary this removes. Bounding that read is tracked separately.)
+ *
+ * The temp directory is removed on a best-effort basis. Throws SfNotFoundError on
+ * ENOENT (sf missing) and rethrows any other spawn error.
+ */
+function captureSpawnToFiles(spawnExecutable, spawnArgs, useShell, resolvedSfPath) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'provar-sf-'));
+    try {
+        return spawnCapturingToDir(dir, spawnExecutable, spawnArgs, useShell, resolvedSfPath);
+    }
+    finally {
+        // Best-effort cleanup: a temp-dir removal failure (e.g. Windows EBUSY/EPERM
+        // from an antivirus/indexer handle, which `force: true` does NOT suppress)
+        // must never overwrite the real return value or mask the real spawn error.
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            /* leave the dir; the OS reclaims its temp directory eventually */
         }
-        throw result.error;
     }
-    return {
-        stdout: result.stdout ?? '',
-        stderr: result.stderr ?? '',
-        exitCode: result.status ?? 1,
+}
+/**
+ * Open the capture files in `dir`, run the child with its stdout/stderr inherited
+ * onto those descriptors, and read the captured output back. Split out from
+ * captureSpawnToFiles so the temp-dir removal in its `finally` also covers the
+ * case where opening the second descriptor fails.
+ */
+function spawnCapturingToDir(dir, spawnExecutable, spawnArgs, useShell, resolvedSfPath) {
+    const outPath = path.join(dir, 'stdout.log');
+    const errPath = path.join(dir, 'stderr.log');
+    const outFd = fs.openSync(outPath, 'w');
+    let errFd;
+    try {
+        errFd = fs.openSync(errPath, 'w');
+    }
+    catch (openErr) {
+        // The first descriptor is already open; close it before unwinding so a
+        // failure to open the second (e.g. EMFILE) doesn't leak it.
+        fs.closeSync(outFd);
+        throw openErr;
+    }
+    let fdsClosed = false;
+    const closeFds = () => {
+        if (fdsClosed)
+            return;
+        fdsClosed = true;
+        try {
+            fs.closeSync(outFd);
+        }
+        catch {
+            /* already closed */
+        }
+        try {
+            fs.closeSync(errFd);
+        }
+        catch {
+            /* already closed */
+        }
     };
+    try {
+        // No `encoding`/`maxBuffer`: stdout/stderr are streamed to the inherited file
+        // descriptors rather than captured in memory, so there is no buffer to overflow.
+        const result = sfSpawnHelper.spawnSync(spawnExecutable, spawnArgs, {
+            shell: useShell,
+            stdio: ['ignore', outFd, errFd],
+        });
+        // spawnSync has already reaped the child, so its writes are flushed to disk;
+        // close our inherited copies of the descriptors before reading the files back.
+        closeFds();
+        if (result.error) {
+            const err = result.error;
+            if (err.code === 'ENOENT') {
+                throw new SfNotFoundError(resolvedSfPath);
+            }
+            throw result.error;
+        }
+        return {
+            stdout: fs.readFileSync(outPath, 'utf-8'),
+            stderr: fs.readFileSync(errPath, 'utf-8'),
+            exitCode: result.status ?? 1,
+        };
+    }
+    finally {
+        closeFds();
+    }
 }
 // ── SOQL safety ───────────────────────────────────────────────────────────────
 /**

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

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

package/lib/mcp/tools/spawnErrors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared error handler for the sf-CLI-backed tools (automation + Quality Hub).
+ * Surfaces a thrown spawn error as an MCP error response, translating a residual
+ * ENOBUFS into actionable remediation and otherwise preserving the error's own
+ * code (falling back to SF_ERROR).
+ */
+export declare function handleSpawnError(err: unknown, requestId: string, toolName: string): {
+    isError: true;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};

package/lib/mcp/tools/spawnErrors.js

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import { makeError } from '../schemas/common.js';
+import { log } from '../logging/logger.js';
+// Defense in depth: runSfCommand streams child output to disk, so a maxBuffer
+// overflow can no longer raise ENOBUFS. Should a residual ENOBUFS still surface
+// (e.g. an exotic OS-level pipe condition), translate the opaque
+// `spawnSync … ENOBUFS` into something the agent can act on rather than retry.
+// Kept tool-agnostic because this handler is shared by every sf-backed tool
+// (automation + Quality Hub); the test-run example is illustrative, not assumed.
+const ENOBUFS_MESSAGE = 'The sf command produced more output than could be captured. Its full output was written to disk ' +
+    '(for test runs, under the resultsPath configured in your provardx-properties.json). ' +
+    'Re-run the command directly in a terminal with --json, or reduce its output verbosity ' +
+    '(for test runs, lower testOutputLevel, e.g. DETAILED → BASIC).';
+const ENOBUFS_SUGGESTION = 'Re-run the sf command directly with --json, or reduce its output verbosity ' +
+    '(for test runs, lower testOutputLevel in provardx-properties.json).';
+/**
+ * Shared error handler for the sf-CLI-backed tools (automation + Quality Hub).
+ * Surfaces a thrown spawn error as an MCP error response, translating a residual
+ * ENOBUFS into actionable remediation and otherwise preserving the error's own
+ * code (falling back to SF_ERROR).
+ */
+export function handleSpawnError(err, requestId, toolName) {
+    const error = err;
+    log('error', `${toolName} failed`, { requestId, error: error.message });
+    if (error.code === 'ENOBUFS') {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(makeError('ENOBUFS', ENOBUFS_MESSAGE, requestId, false, { suggestion: ENOBUFS_SUGGESTION })),
+                },
+            ],
+        };
+    }
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(makeError(error.code ?? 'SF_ERROR', error.message, requestId, false)),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=spawnErrors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spawnErrors.js","sourceRoot":"","sources":["../../../src/mcp/tools/spawnErrors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAE3C,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,MAAM,eAAe,GACnB,kGAAkG;IAClG,sFAAsF;IACtF,wFAAwF;IACxF,gEAAgE,CAAC;AACnE,MAAM,kBAAkB,GACtB,6EAA6E;IAC7E,qEAAqE,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAY,EACZ,SAAiB,EACjB,QAAgB;IAEhB,MAAM,KAAK,GAAG,GAAgC,CAAC;IAC/C,GAAG,CAAC,OAAO,EAAE,GAAG,QAAQ,SAAS,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACxE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO;YACL,OAAO,EAAE,IAAa;YACtB,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAC5F;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE,IAAa;QACtB,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,IAAI,UAAU,EAAE,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;aAC3F;SACF;KACF,CAAC;AACJ,CAAC"}

package/lib/mcp/tools/testCaseGenerate.js

@@ -12,6 +12,7 @@ import { z } from 'zod';
 import { assertPathAllowed, PathPolicyError } from '../security/pathPolicy.js';
 import { makeError, makeRequestId } from '../schemas/common.js';
 import { log } from '../logging/logger.js';
+import { allocateTestCaseId, DEFAULT_TESTCASE_ID } from '../utils/testCaseId.js';
 import { validateTestCase } from './testCaseValidate.js';
 import { desc } from './descHelper.js';
 import { UI_ACTION_API_IDS, UI_SCREEN_CONTAINER_API_IDS, UI_LOCATOR_BEARING_API_IDS } from './uiActionApiIds.js';
@@ -165,7 +166,7 @@ const TOOL_DESCRIPTION = [
     // ── Existing description (unchanged below) ───────────────────────────────────
     '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>.',
+    'Generated structure: <?xml version="1.0" encoding="UTF-8" standalone="no"?> with <testCase guid="..." id="N" registryId="..."> (a numeric integer id), a <summary/> child, then <steps>. The unique identifier is the guid; id is a human-facing label. When writing into an existing project the id is auto-allocated as the highest in-use id + 1; otherwise it defaults to 1.',
     '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.',
@@ -190,9 +191,9 @@ const TOOL_DESCRIPTION = [
     'target argument (UiWithScreen/UiWithRow): pass the URI value; emitted as class="uiTarget" uri="...".',
     'locator argument (UiDoAction/UiAssert/UiRead/UiFill): pass the URI value; emitted as class="uiLocator" uri="...".',
     'valueClass auto-detection: argument values are typed automatically before XML emission. ' +
-        'ISO-8601 date "YYYY-MM-DD" → valueClass="date"; ISO-8601 datetime "YYYY-MM-DDTHH:MM:SS" (optional fractional seconds + timezone) → "datetime"; ' +
+        'ISO-8601 date "YYYY-MM-DD" → valueClass="date"; ISO-8601 datetime "YYYY-MM-DDTHH:MM:SS" (optional fractional seconds + timezone) → "dateTime"; ' +
         '"true"/"false" → "boolean"; numeric string (e.g. "42", "-5", "3.14") → "decimal"; otherwise "string". ' +
-        'Pass dates / booleans / numbers in those formats — Provar runtime silently discards date fields emitted as valueClass="string". ' +
+        'Pass dates in ISO-8601 — the generator converts them to the epoch-millisecond value Provar requires (a date/dateTime field emitted as an ISO string, or as valueClass="string", fails to load in the IDE). A bare date is treated as UTC midnight; a datetime without a timezone is treated as UTC. ' +
         'Note: numbers always emit valueClass="decimal" per the canonical Provar reference (there is no separate "integer" valueClass).',
     '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. ' +
@@ -303,11 +304,18 @@ export function registerTestCaseGenerate(server, config) {
             return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
         }
         try {
-            const xmlContent = buildTestCaseXml(input);
             const filePath = input.output_path ? path.resolve(input.output_path) : undefined;
-            let written = false;
+            // Allocate the root testCase id from surrounding project context, but only
+            // when actually persisting (a write path that has cleared the path policy).
+            // Preview/dry-run runs have no project anchor, so they keep the default id.
+            let idAllocation = { id: DEFAULT_TESTCASE_ID, basis: 'default' };
             if (filePath && !input.dry_run) {
                 assertPathAllowed(filePath, config.allowedPaths);
+                idAllocation = allocateTestCaseId(filePath, config.allowedPaths);
+            }
+            const xmlContent = buildTestCaseXml(input, idAllocation.id);
+            let written = false;
+            if (filePath && !input.dry_run) {
                 if (fs.existsSync(filePath) && !input.overwrite) {
                     const err = makeError('FILE_EXISTS', `File already exists: ${filePath}. Set overwrite=true to replace.`, requestId);
                     return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
@@ -315,7 +323,12 @@ 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,
+                    testCaseId: idAllocation.id,
+                    idBasis: idAllocation.basis,
+                });
             }
             const warnings = buildStepWarnings(input.steps);
             const runValidation = input.validate_after_edit !== false;
@@ -326,6 +339,7 @@ export function registerTestCaseGenerate(server, config) {
                 written,
                 dry_run: input.dry_run,
                 step_count: input.steps.length,
+                test_case_id: idAllocation.id,
                 idempotency_key: input.idempotency_key,
                 ...(warnings.length > 0 ? { warnings } : {}),
             };
@@ -450,13 +464,47 @@ function buildArgumentValue(key, val, indent, inNamedValues = false, apiId = '')
         if (key === 'locator' && UI_LOCATOR_BEARING_API_IDS.has(apiId)) {
             return `${indent}<value class="uiLocator" uri="${escapeXmlAttr(val)}"/>`;
         }
+        // D2: 'interaction' argument → class="uiInteraction" (UiDoAction Action widget).
+        // PDX-506: the IDE step editor binds its Action only from a typed uiInteraction;
+        // a plain string runs green from the CLI but renders the Action field blank.
+        // Gated on the shared UI-action API set so generator + validator stay aligned.
+        if (key === 'interaction' && UI_ACTION_API_IDS.has(apiId)) {
+            return `${indent}<value class="uiInteraction" uri="${escapeXmlAttr(val)}"/>`;
+        }
     }
     // PDX-493 (H3): infer valueClass for date / datetime / boolean / decimal / string. The
     // `fieldTypeHint` parameter on `inferSalesforceValueClass` is intentionally not threaded
     // through here yet — it lands in PDX-492 (H2b) along with the `field_type_hints` tool input.
     const inferred = inferSalesforceValueClass(key, val);
+    if (inferred === 'date' || inferred === 'datetime') {
+        // PDX-509: Provar stores date/dateTime as epoch MILLISECONDS, never an ISO string —
+        // an ISO string fails to load in the IDE (RENDER-DATE-VALUECLASS-001), and the real
+        // corpus uses epoch ms exclusively with camelCase `dateTime`. Convert here.
+        const ms = isoToEpochMs(val, inferred);
+        if (ms !== null) {
+            const valueClass = inferred === 'datetime' ? 'dateTime' : 'date';
+            return `${indent}<value class="value" valueClass="${valueClass}">${ms}</value>`;
+        }
+        // A value that matches the ISO shape but is not a real date (e.g. "2026-99-99")
+        // cannot be converted — fall back to a plain string rather than emit a
+        // load-breaking date/dateTime with a non-epoch value.
+        return `${indent}<value class="value" valueClass="string">${escapeXmlContent(val)}</value>`;
+    }
     return `${indent}<value class="value" valueClass="${inferred}">${escapeXmlContent(val)}</value>`;
 }
+/**
+ * Convert a validated ISO-8601 date / datetime string to epoch milliseconds.
+ * A date-only string ("YYYY-MM-DD") is parsed as UTC midnight per the ES spec. A
+ * datetime WITHOUT an explicit timezone would otherwise parse as machine-local
+ * time (non-deterministic), so we pin it to UTC by appending 'Z' — matching the
+ * Provar corpus, where date/dateTime values are stored as UTC epoch ms.
+ * Returns null if the value cannot be parsed (caller falls back to the raw text).
+ */
+function isoToEpochMs(val, kind) {
+    const needsUtc = kind === 'datetime' && !/(Z|[+-]\d{2}:?\d{2})$/.test(val);
+    const ms = Date.parse(needsUtc ? `${val}Z` : val);
+    return Number.isNaN(ms) ? null : ms;
+}
 function buildArgumentsXml(attributes, baseIndent = '      ', apiId = '') {
     const entries = Object.entries(attributes);
     if (entries.length === 0)
@@ -493,6 +541,82 @@ function buildSetValuesXml(attributes, baseIndent) {
         `${i(0)}</arguments>\n` +
         `${baseIndent.slice(0, -2)}`);
 }
+// PDX-507: derive the field name for a uiFieldAssertion from a locator URI's
+// `name=` parameter (e.g. ui:locator?name=LastName&binding=… → "LastName").
+function extractFieldName(uri) {
+    const m = /[?&]name=([^&]*)/.exec(uri);
+    if (!m)
+        return 'Field';
+    try {
+        return decodeURIComponent(m[1]) || 'Field';
+    }
+    catch {
+        return m[1] || 'Field';
+    }
+}
+// PDX-507: UiAssert — assemble the nested fieldAssertions / uiFieldAssertion
+// structure the Provar IDE Result Assertions tab binds from. The generator
+// previously emitted the flat shape (top-level fieldLocator / attributeName /
+// comparisonType / expectedValue arguments), which runs green from the CLI but
+// renders the Result Assertions tab blank in the IDE. Shape confirmed against
+// the real test corpus (AllPOCProjects): 3,743/3,778 UiAssert steps use this
+// nested form, with a BARE <fieldLocator uri="…"/> element (never class="uiLocator"
+// — see best-practice rule UI-ASSERT-FIELDLOCATOR-002) and no `assertionType`.
+// Only a `fieldLocator` attribute triggers the nested form; a UiAssert that
+// carries a plain `locator` argument keeps the documented locator→uiLocator
+// contract via the flat fallback (buildArgumentValue dispatches it). When no
+// fieldLocator is supplied the step is not a field assertion, so fall back to
+// flat argument emission and leave other UiAssert shapes untouched.
+function buildUiAssertXml(attributes, baseIndent, apiId) {
+    const a = attributes;
+    const fieldLocator = a['fieldLocator'] ?? '';
+    if (!fieldLocator)
+        return buildArgumentsXml(attributes, baseIndent, apiId);
+    const i = (n) => baseIndent + '  '.repeat(n);
+    const resultName = a['resultName'] ?? 'Values';
+    const resultScope = a['resultScope'] ?? 'Test';
+    const captureAfter = a['captureAfter'] ?? 'false';
+    const attributeName = a['attributeName'] ?? 'value';
+    const comparisonType = a['comparisonType'] ?? 'EqualTo';
+    const fieldName = extractFieldName(fieldLocator);
+    const expected = a['expectedValue'];
+    // resultName / resultScope / captureAfter are control-plane literals that the
+    // real corpus ALWAYS emits as valueClass="string" — including captureAfter
+    // ("true"/"false"), which is intentionally NOT valueClass="boolean" here.
+    // Routing these through inferSalesforceValueClass would diverge from the
+    // corpus (it would infer boolean), so they are emitted as string literals.
+    const strVal = (v) => `<value class="value" valueClass="string">${escapeXmlContent(v)}</value>`;
+    // uiAttributeAssertion — self-closing when there is no expected value. This is
+    // a real corpus form (e.g. ADP_POV "UI Assert - Date Empty" emits
+    // <uiAttributeAssertion attributeName="value" comparisonType="EqualTo"/>);
+    // otherwise it carries a typed <value> child built via buildArgumentValue so
+    // {Var} expands to class="variable".
+    const attrOpen = `${i(5)}<uiAttributeAssertion attributeName="${escapeXmlAttr(attributeName)}" comparisonType="${escapeXmlAttr(comparisonType)}"`;
+    const attrAssertion = expected != null && expected !== ''
+        ? `${attrOpen}>\n${buildArgumentValue('expectedValue', expected, i(6), true)}\n${i(5)}</uiAttributeAssertion>`
+        : `${attrOpen}/>`;
+    const fieldAssertion = `${i(4)}<uiFieldAssertion resultName="${escapeXmlAttr(fieldName)}">\n` +
+        `${i(5)}<fieldLocator uri="${escapeXmlAttr(fieldLocator)}"/>\n` +
+        `${i(5)}<attributeAssertions>\n` +
+        `${attrAssertion}\n` +
+        `${i(5)}</attributeAssertions>\n` +
+        `${i(4)}</uiFieldAssertion>`;
+    return (`\n${i(0)}<arguments>\n` +
+        `${i(0)}<argument id="resultName">\n${i(1)}${strVal(resultName)}\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="resultScope">\n${i(1)}${strVal(resultScope)}\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="fieldAssertions">\n` +
+        `${i(1)}<value class="valueList" mutable="Mutable">\n` +
+        `${fieldAssertion}\n` +
+        `${i(1)}</value>\n` +
+        `${i(0)}</argument>\n` +
+        `${i(0)}<argument id="captureAfter">\n${i(1)}${strVal(captureAfter)}\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="columnAssertions">\n${i(1)}<value class="valueList" mutable="Mutable"/>\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="pageAssertions">\n${i(1)}<value class="valueList" mutable="Mutable"/>\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="beforeWait"/>\n` +
+        `${i(0)}<argument id="autoRetry"/>\n` +
+        `${i(0)}</arguments>\n` +
+        `${baseIndent.slice(0, -2)}`);
+}
 function buildFlatStepXml(step, testItemId, indent) {
     return buildStepXmlWithChildren(step, testItemId, indent, '', undefined);
 }
@@ -510,9 +634,17 @@ function buildStepXmlWithChildren(step, testItemId, indent, childrenXml, substep
     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);
+    // PDX-507: UiAssert uses the nested fieldAssertions/uiFieldAssertion structure.
+    let argumentsXml;
+    if (resolvedApiId.includes('SetValues')) {
+        argumentsXml = buildSetValuesXml(step.attributes, baseIndent);
+    }
+    else if (resolvedApiId.endsWith('.UiAssert') || resolvedApiId === 'UiAssert') {
+        argumentsXml = buildUiAssertXml(step.attributes, baseIndent, resolvedApiId);
+    }
+    else {
+        argumentsXml = buildArgumentsXml(step.attributes, baseIndent, resolvedApiId);
+    }
     const hasClauses = substepsTestItemId !== undefined;
     const open = `${indent}<apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}" name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}">`;
     const close = `${indent}</apiCall>`;
@@ -614,7 +746,7 @@ function emitGroupedSteps(nodes, indent, startId) {
     }
     return { xml: lines.join('\n'), nextId: id };
 }
-function buildTestCaseXml(input) {
+function buildTestCaseXml(input, testCaseId = DEFAULT_TESTCASE_ID) {
     const testCaseGuid = randomUUID();
     const registryId = randomUUID();
     const groupingMode = input.grouping_mode ?? 'auto';
@@ -660,9 +792,11 @@ function buildTestCaseXml(input) {
         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>.
+    // Provar requires: standalone="no", a numeric integer id, no name attr, <summary/> before <steps>.
+    // The id is a human-facing label, not a uniqueness key (guid is) — see allocateTestCaseId:
+    // when writing into an existing project we pass highest-in-use + 1; otherwise it defaults to 1.
     return ('<?xml version="1.0" encoding="UTF-8" standalone="no"?>\n' +
-        `<testCase guid="${testCaseGuid}" id="1" registryId="${registryId}">\n` +
+        `<testCase guid="${testCaseGuid}" id="${testCaseId}" registryId="${registryId}">\n` +
         '  <summary/>\n' +
         '  <steps>\n' +
         stepLines +