trxa-tool 0.0.0-stage → 0.2.0

package/dist/library-archive.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Every top-level directory a library backup bundles. `testscripts/` is included even though it's
+ * derived (via `parse`) from `recordings/` -- a personal backup isn't a shared-repo commit, and
+ * including it saves re-running `parse` on every recording after a restore, at the cost of a
+ * bigger archive.
+ */
+export declare const LIBRARY_DIRS: string[];
+export interface LibraryZipBuffer {
+    buffer: Buffer;
+    fileCount: number;
+    dirs: string[];
+}
+/** Bundles every {@link LIBRARY_DIRS} directory under `baseDir` into an in-memory zip buffer --
+ *  the shared core both the CLI's file-writing `exportLibrary` and the Studio server's
+ *  streaming-response route build on. */
+export declare function buildLibraryZip(baseDir: string): Promise<LibraryZipBuffer>;
+export interface ExportResult {
+    outPath: string;
+    fileCount: number;
+    dirs: string[];
+}
+/** Bundles every {@link LIBRARY_DIRS} directory under `baseDir` into a zip at `outPath`. */
+export declare function exportLibrary(baseDir: string, outPath: string): Promise<ExportResult>;
+export interface ImportResult {
+    fileCount: number;
+    collisions: string[];
+}
+/**
+ * Unpacks a library backup zip (already read into memory) into `baseDir`. Refuses (writing
+ * nothing) if any target file already exists, unless `force` is set -- a silent overwrite of test
+ * cases, fixtures, or recorded runs is exactly the kind of mistake this check exists to prevent.
+ * Shared core for both the CLI's file-reading `importLibrary` and the Studio server's upload
+ * route, which already has the bytes in memory from the request body.
+ */
+export declare function extractLibraryZip(bytes: Buffer, baseDir: string, force: boolean): Promise<ImportResult>;
+/** Reads `zipPath` off disk and unpacks it into `baseDir` -- see {@link extractLibraryZip}. */
+export declare function importLibrary(zipPath: string, baseDir: string, force: boolean): Promise<ImportResult>;

package/dist/library-archive.js

@@ -0,0 +1,106 @@
+import { readFile, writeFile, readdir, mkdir, stat } from "node:fs/promises";
+import path from "node:path";
+import JSZip from "jszip";
+/**
+ * Every top-level directory a library backup bundles. `testscripts/` is included even though it's
+ * derived (via `parse`) from `recordings/` -- a personal backup isn't a shared-repo commit, and
+ * including it saves re-running `parse` on every recording after a restore, at the cost of a
+ * bigger archive.
+ */
+export const LIBRARY_DIRS = ["recordings", "testcases", "testdata", "testscripts", "suites", "plans", "testruns"];
+async function fileExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function addDirToZip(zip, dirAbsPath, zipPrefix) {
+    let entries;
+    try {
+        entries = await readdir(dirAbsPath, { withFileTypes: true });
+    }
+    catch {
+        // Directory doesn't exist -- nothing to bundle from it, same "empty, not an error" tradeoff
+        // used elsewhere for optional library directories (see loadFixtures in index.ts).
+        return 0;
+    }
+    let count = 0;
+    for (const entry of entries) {
+        const abs = path.join(dirAbsPath, entry.name);
+        const zipPath = `${zipPrefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            count += await addDirToZip(zip, abs, zipPath);
+        }
+        else if (entry.isFile()) {
+            zip.file(zipPath, await readFile(abs));
+            count++;
+        }
+    }
+    return count;
+}
+/** Bundles every {@link LIBRARY_DIRS} directory under `baseDir` into an in-memory zip buffer --
+ *  the shared core both the CLI's file-writing `exportLibrary` and the Studio server's
+ *  streaming-response route build on. */
+export async function buildLibraryZip(baseDir) {
+    const zip = new JSZip();
+    let fileCount = 0;
+    for (const dir of LIBRARY_DIRS) {
+        fileCount += await addDirToZip(zip, path.join(baseDir, dir), dir);
+    }
+    const buffer = await zip.generateAsync({ type: "nodebuffer", compression: "DEFLATE" });
+    return { buffer, fileCount, dirs: LIBRARY_DIRS };
+}
+/** Bundles every {@link LIBRARY_DIRS} directory under `baseDir` into a zip at `outPath`. */
+export async function exportLibrary(baseDir, outPath) {
+    const { buffer, fileCount, dirs } = await buildLibraryZip(baseDir);
+    await mkdir(path.dirname(path.resolve(outPath)), { recursive: true });
+    await writeFile(outPath, buffer);
+    return { outPath, fileCount, dirs };
+}
+/**
+ * Unpacks a library backup zip (already read into memory) into `baseDir`. Refuses (writing
+ * nothing) if any target file already exists, unless `force` is set -- a silent overwrite of test
+ * cases, fixtures, or recorded runs is exactly the kind of mistake this check exists to prevent.
+ * Shared core for both the CLI's file-reading `importLibrary` and the Studio server's upload
+ * route, which already has the bytes in memory from the request body.
+ */
+export async function extractLibraryZip(bytes, baseDir, force) {
+    const zip = await JSZip.loadAsync(bytes);
+    const entries = Object.values(zip.files).filter((f) => !f.dir);
+    const baseAbs = path.resolve(baseDir);
+    const targets = [];
+    for (const entry of entries) {
+        const topDir = entry.name.split("/")[0];
+        if (!LIBRARY_DIRS.includes(topDir)) {
+            throw new Error(`Refusing to import: "${entry.name}" is outside the recognized library directories (${LIBRARY_DIRS.join(", ")}) -- this doesn't look like an trxa-tool library backup.`);
+        }
+        const targetPath = path.resolve(baseAbs, entry.name);
+        if (!targetPath.startsWith(baseAbs + path.sep)) {
+            throw new Error(`Refusing to import: "${entry.name}" resolves outside the target directory.`);
+        }
+        targets.push({ entry, targetPath });
+    }
+    if (!force) {
+        const collisions = [];
+        for (const { entry, targetPath } of targets) {
+            if (await fileExists(targetPath))
+                collisions.push(entry.name);
+        }
+        if (collisions.length > 0) {
+            return { fileCount: 0, collisions };
+        }
+    }
+    for (const { entry, targetPath } of targets) {
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, await entry.async("nodebuffer"));
+    }
+    return { fileCount: targets.length, collisions: [] };
+}
+/** Reads `zipPath` off disk and unpacks it into `baseDir` -- see {@link extractLibraryZip}. */
+export async function importLibrary(zipPath, baseDir, force) {
+    const bytes = await readFile(zipPath);
+    return extractLibraryZip(bytes, baseDir, force);
+}

package/dist/mapping.d.ts

@@ -0,0 +1,25 @@
+import type { TestStep } from "./normalize.js";
+export type Confidence = "high" | "medium" | "low";
+export interface FollowUp {
+    tool: string;
+    note: string;
+}
+/**
+ * A *hint*, not a compiled instruction: the orchestrating LLM should treat `params` as a
+ * starting guess and fall back to form_find_controls / form_find_menu_item to resolve the
+ * real target when confidence is "low" or the hinted call fails.
+ *
+ * Param shapes below were validated against the real d365-erp-mcp tool schemas (and, for
+ * form_select_grid_row / form_filter_grid / form_save_form, against a live replay) rather than
+ * guessed from the recording alone -- see ARCHITECTURE.md "Learnings from a live dry run".
+ */
+export interface McpToolHint {
+    tool: string;
+    confidence: Confidence;
+    params: Record<string, unknown>;
+    note?: string;
+    /** Additional tool calls the orchestrator should make after this one, e.g. form_save_form. */
+    followUp?: FollowUp[];
+}
+/** Maps a normalized TestStep to a best-effort d365-erp-mcp tool call hint. Null for Unknown nodes. */
+export declare function mapStep(step: TestStep): McpToolHint | null;

package/dist/mapping.js

@@ -0,0 +1,393 @@
+/**
+ * D365FO's Task Recorder marks some steps SystemGenerated=true -- automatic side effects (e.g. a
+ * form part lazy-loading once its parent tab becomes visible) rather than anything the user did.
+ * Confirmed live: recordings/BPM-AXTR-Add a new Delivery address.axtr's OpenFormPart step has
+ * SystemGenerated=true and no corresponding user action exists to replay.
+ */
+function skipHint(step) {
+    if (step.node.kind === "Scope" || !step.node.SystemGenerated)
+        return null;
+    return {
+        tool: "skip",
+        confidence: "high",
+        params: {},
+        note: "SystemGenerated=true in the recording; this was an automatic side effect, not a user action. Nothing to replay for this step.",
+    };
+}
+function menuItemHint(step) {
+    if (step.node.kind !== "MenuItemUserAction")
+        return null;
+    return {
+        tool: "form_open_menu_item",
+        confidence: "high",
+        params: { name: step.node.MenuItemName, type: step.node.MenuItemType },
+    };
+}
+function commandHint(step) {
+    if (step.node.kind !== "CommandUserAction")
+        return null;
+    const { CommandName, ControlName, ControlType } = step.node;
+    if (ControlType === "Grid" && CommandName === "ChangeSelectedIndexInCache") {
+        return {
+            tool: "form_filter_grid",
+            confidence: "low",
+            params: { gridName: ControlName },
+            note: "Recording selects a grid row by recorded position (Arguments), which is not portable " +
+                "across environments/data. Confirmed on a live replay where the recorded index no " +
+                "longer pointed at the intended record. Identify the target record from surrounding " +
+                "step context (e.g. a business key mentioned in the description) and supply " +
+                "gridColumnName/gridColumnValue to filter the grid to it before selecting a row.",
+        };
+    }
+    if (ControlType === "Grid" && (CommandName === "NavigationAction" || CommandName === "MarkActiveRow")) {
+        return {
+            tool: "form_select_grid_row",
+            confidence: "low",
+            params: { gridName: ControlName },
+            note: "Requires rowNumber (read it off the current grid state after filtering) and, per " +
+                "d365-erp-mcp's own per-grid guidance, usually a marking parameter " +
+                '("Marked" to check the row\'s selection box, "Unmarked" to just navigate/highlight it).',
+        };
+    }
+    if (ControlType === "AppBarTab") {
+        return {
+            tool: "form_click_control",
+            confidence: "high",
+            params: { controlName: ControlName },
+            note: "Action Pane / ribbon tab selection.",
+        };
+    }
+    if (ControlType === "Tab" ||
+        (ControlType === "SectionPage" && CommandName === "ExpandedChanged") ||
+        (ControlType === "PivotItem" && CommandName === "ActivateTab")) {
+        return {
+            tool: "form_open_or_close_tab",
+            confidence: "high",
+            params: { tabName: ControlName, tabAction: "Open" },
+            note: ControlType === "SectionPage"
+                ? "Confirmed live (form_open_or_close_tab works identically on ControlType=SectionPage, not just Tab). " +
+                    "Recording can't tell you whether the user expanded or collapsed the section. Check the current " +
+                    "FormState's Tab[name].IsOpen and only call this if it doesn't already match; use tabAction=\"Close\" instead if collapsing."
+                : ControlType === "PivotItem"
+                    ? "Confirmed live on a purchase order line's detail Pivot (e.g. TabLineProject): opening one PivotItem " +
+                        "auto-closes whichever sibling was open, so tabAction=\"Open\" is always the right call here (unlike " +
+                        "Tab/SectionPage, there's no independent collapse state to worry about)."
+                    : undefined,
+        };
+    }
+    if (CommandName === "RequestPopup" && ControlType === "Input") {
+        return {
+            tool: "form_open_lookup",
+            confidence: "high",
+            params: { lookupName: ControlName },
+            note: "Confirmed live against a multi-select Purpose/Roles lookup: opens a SysLookupMultiSelectGrid-style " +
+                "popup form. Follow its own returned Guidance for how to select rows and confirm/cancel.",
+        };
+    }
+    if (CommandName === "RequestPopup" && ControlType === "DropDialogButton") {
+        return {
+            tool: "form_click_control",
+            confidence: "high",
+            params: { controlName: ControlName },
+            note: "Confirmed live (e.g. the 'New from template' split button on Free text invoice): a DropDialogButton " +
+                "opens its popup via a plain click, same as CLICKABLE_CONTROL_TYPES below. Unlike RequestPopup on an " +
+                "Input control, this is not a lookup.",
+        };
+    }
+    if (CommandName === "ExecuteHyperlink" && ControlType === "Input") {
+        return {
+            tool: "form_click_control",
+            confidence: "high",
+            params: { controlName: ControlName },
+            note: "Confirmed live (e.g. clicking a grid row's Name/description link to open its edit dialog): hyperlink-style " +
+                "Input fields are clicked the same way as any other control, despite the different CommandName.",
+        };
+    }
+    if (CommandName === "SelectionPathChanged" && ControlType === "Tree") {
+        return {
+            tool: "form_click_control",
+            confidence: "medium",
+            params: { controlName: ControlName },
+            note: "Confirmed live on a category tree lookup (EcoResCategorySingleLookup/ctrlFormTree): tree nodes are " +
+                'clicked via actionId, formatted "Select:<n>" or "Expand:<n>" per the current FormState\'s Tree[name]' +
+                ".Nodes[].Actions. Not a plain click. The node index is a live-session identifier, not portable from " +
+                "the recording (same non-portability caveat as grid row selection): find the target node by matching " +
+                "its Text to the business value you want, expanding parent nodes first if needed, then click with that " +
+                "node's own Actions.Select id.",
+        };
+    }
+    if (CommandName === "RequestClose") {
+        return {
+            tool: "form_close_form",
+            confidence: "high",
+            params: {},
+            note: "Confirmed live: closes the current popup/dialog with no ControlName needed (matches how these steps " +
+                "are recorded; there's no associated button). Some forms with explicit OK/Cancel buttons ask you to use " +
+                "those buttons instead of a direct close; in that case the recording captures a separate Click step " +
+                "on the button, not RequestClose.",
+        };
+    }
+    if (ControlName === "buttonUpdateConfirm" && CommandName === "Click") {
+        return {
+            tool: "form_open_menu_item",
+            confidence: "medium",
+            params: { name: "SalesFormLetter_Confirmation", type: "Action" },
+            note: "Confirmed live (headless intercompany replay, 2026-08-20): buttonUpdateConfirm wasn't " +
+                "reachable on the SalesTable order form in this environment. Invoke the " +
+                "SalesFormLetter_Confirmation action menu item directly instead of clicking the recorded " +
+                "button.",
+        };
+    }
+    if (ControlName === "buttonUpdateInvoice" && CommandName === "Click") {
+        return {
+            tool: "form_click_control",
+            confidence: "high",
+            params: { controlName: ControlName },
+            note: "Confirmed live (headless intercompany replay, 2026-08-20) on an intercompany purchase " +
+                "order (DEMF): clicking buttonUpdateInvoice from the PO form itself opened a USMF-scoped, " +
+                "empty vendor-invoice list; company context didn't carry through. Clicking it from the " +
+                "DEMF list page instead, with the target row marked and companyId set explicitly on that " +
+                "navigation, opened a correctly pre-populated invoice.",
+        };
+    }
+    if (ControlName === "ButtonInterCompanyCustPackingSlipJournal" && CommandName === "Click") {
+        return {
+            tool: "form_click_control",
+            confidence: "high",
+            params: { controlName: ControlName },
+            followUp: [
+                {
+                    tool: "form_click_control",
+                    note: "Confirmed live (headless intercompany replay, 2026-08-20): generating an intercompany " +
+                        "product receipt needs an explicit follow-up click on ButtonInterCompanyUpdate; " +
+                        "posting the sales-side packing slip alone doesn't produce it.",
+                },
+            ],
+        };
+    }
+    const CLICKABLE_CONTROL_TYPES = new Set([
+        "CommandButton",
+        "MenuItemButton",
+        "MenuButton",
+        "MenuItem",
+        "Button",
+    ]);
+    if (CommandName === "Click" && CLICKABLE_CONTROL_TYPES.has(ControlType)) {
+        const isNestedMenuChild = ControlType === "MenuButton" || ControlType === "MenuItem";
+        return {
+            tool: "form_click_control",
+            confidence: "high",
+            params: { controlName: ControlName },
+            ...(isNestedMenuChild && {
+                note: "Nested menu button children (ControlType MenuButton/MenuItem) could be clicked " +
+                    "directly by name on a live replay; no separate 'open the dropdown' step was " +
+                    "needed even though the recording captured two clicks.",
+            }),
+        };
+    }
+    const filterOrSortHint = filterManagerHint(step.node);
+    if (filterOrSortHint)
+        return filterOrSortHint;
+    const investigated = INVESTIGATED_BUT_UNVERIFIED[`${CommandName}:${ControlType}`];
+    return {
+        tool: "form_find_controls",
+        confidence: "low",
+        params: { controlSearchTerm: ControlName },
+        note: investigated
+            ? `Unmapped CommandUserAction (CommandName=${CommandName}, ControlType=${ControlType}). ${investigated}`
+            : `Unmapped CommandUserAction (CommandName=${CommandName}, ControlType=${ControlType}). Resolve via form_find_controls before acting.`,
+    };
+}
+function parseJson(raw) {
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function filterGridColumnName(meta) {
+    return `${meta.DataSourceName}_${meta.FieldName}`;
+}
+/**
+ * D365FO's recorded filter Operator translated to the wildcard syntax form_filter_grid's own
+ * schema documents (SysQueryRangeUtil-style range strings) -- confirmed live for the no-wildcard
+ * (exact/Matches) case; Contains/EndsWith follow the same documented convention but haven't been
+ * live-tested with those specific operators yet.
+ */
+function filterOperatorToValue(operator, value) {
+    if (!value)
+        return "";
+    switch (operator) {
+        case "BeginsWith":
+            return `${value}*`;
+        case "Contains":
+            return `*${value}*`;
+        case "EndsWith":
+            return `*${value}`;
+        default:
+            return value;
+    }
+}
+const FILTER_MANAGER_GRID_NAME_NOTE = "gridName isn't recorded on this step and isn't always \"Grid\". Standard lookup popups " +
+    "(e.g. CustTableLookup) commonly expose exactly one grid literally named \"Grid\" (confirmed " +
+    "live), but list-page forms (e.g. PurchTable) don't; confirm the real gridName from the " +
+    "current FormState before calling.";
+/**
+ * The FilterManager/QuickFilter/FilterPane command family: the recorded ControlName is always the
+ * filter/sort UI itself (e.g. SystemDefinedFilterManager), never the grid it acts on, so it can't
+ * be passed through as gridName directly. Confirmed live against CustTableLookup's "Grid" (see
+ * recordings/BPM-AXTR-Create a free text invoice.axtr) and cross-checked against the JSON shape
+ * on every occurrence of these CommandNames across the full recordings library (not just one
+ * sample): each step's Arguments carries a JSON string with the real DataSourceName/FieldName
+ * (and, for filters, an Operator + Values; for sorts, a human-readable direction). gridColumnName
+ * is consistently DataSourceName_FieldName -- confirmed by comparing the parsed metadata against
+ * the live FormState's actual column names (CustTable_AccountNum, not just AccountNum).
+ */
+function filterManagerHint(node) {
+    if (node.kind !== "CommandUserAction")
+        return null;
+    const { CommandName, ControlType, Arguments } = node;
+    if (CommandName === "GetFilters" && ControlType === "FilterManager") {
+        return {
+            tool: "skip",
+            confidence: "medium",
+            params: {},
+            note: "Confirmed across every GetFilters:FilterManager occurrence in the recordings library: " +
+                "the embedded filter-field JSON always has an empty Values array. This step just opens/" +
+                "reads the column filter dropdown for display; nothing to replay. If a future recording " +
+                "ever shows a non-empty Values here, treat it like ApplyFiltersForTaskRecorder instead.",
+        };
+    }
+    if (CommandName === "SetSortsForTaskRecorder" && ControlType === "FilterManager") {
+        const meta = parseJson(Arguments[0]?.Value)?.[0];
+        const direction = Arguments[Arguments.length - 1]?.Value;
+        if (meta && direction) {
+            return {
+                tool: "form_sort_grid_column",
+                confidence: "medium",
+                params: {
+                    gridColumnName: filterGridColumnName(meta),
+                    sortDirection: /z to a/i.test(direction) ? "Descending" : "Ascending",
+                },
+                note: `sortDirection parsed from the recording's human-readable direction ("${direction}"). ${FILTER_MANAGER_GRID_NAME_NOTE}`,
+            };
+        }
+    }
+    if (CommandName === "ApplyFiltersForTaskRecorder" && ControlType === "FilterManager") {
+        const meta = parseJson(Arguments[0]?.Value)?.[0];
+        if (meta) {
+            return {
+                tool: "form_filter_grid",
+                confidence: "medium",
+                params: {
+                    gridColumnName: filterGridColumnName(meta),
+                    gridColumnValue: filterOperatorToValue(meta.Operator, meta.Values?.[0] ?? ""),
+                },
+                note: FILTER_MANAGER_GRID_NAME_NOTE,
+            };
+        }
+    }
+    if (CommandName === "ApplyFilterForTaskRecorder" && ControlType === "QuickFilter") {
+        const meta = parseJson(Arguments[2]?.Value);
+        if (meta) {
+            return {
+                tool: "form_filter_grid",
+                confidence: "medium",
+                params: { gridColumnName: meta.FieldName, gridColumnValue: meta.Value },
+                note: "gridColumnName/gridColumnValue parsed directly from the step's embedded JSON (already " +
+                    `DataSource_Field form here, e.g. "ProjTable_Name", unlike the FilterManager family). ${FILTER_MANAGER_GRID_NAME_NOTE}`,
+            };
+        }
+    }
+    if (CommandName === "ApplyFilters" && ControlType === "FilterPane") {
+        const metas = (parseJson(Arguments[2]?.Value) ?? []).filter((m) => (m.Values?.[0] ?? "") !== "");
+        if (metas.length > 0) {
+            const [first, ...rest] = metas;
+            return {
+                tool: "form_filter_grid",
+                confidence: "medium",
+                params: {
+                    gridColumnName: filterGridColumnName(first),
+                    gridColumnValue: filterOperatorToValue(first.Operator, first.Values[0]),
+                },
+                followUp: rest.map((m) => ({
+                    tool: "form_filter_grid",
+                    note: `Also apply gridColumnName=${filterGridColumnName(m)}, gridColumnValue=${filterOperatorToValue(m.Operator, m.Values[0])} on the same grid.`,
+                })),
+                note: "A FilterPane step can carry filters for multiple fields at once; fields with an empty " +
+                    `recorded value are omitted (blank means "no filter" for that field, not "clear it"). ${FILTER_MANAGER_GRID_NAME_NOTE}`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Fallback notes for the FilterManager/QuickFilter/FilterPane family above, used only if the
+ * embedded Arguments JSON is missing or fails to parse (filterManagerHint returns null and control
+ * falls through to the generic form_find_controls fallback in commandHint).
+ */
+const INVESTIGATED_BUT_UNVERIFIED = {
+    "GetFilters:FilterManager": "Expected empty Arguments; see filterManagerHint in this file.",
+    "ApplyFilterForTaskRecorder:QuickFilter": "Expected Arguments[2] to be JSON with FieldName/Value; see filterManagerHint in this file.",
+    "ApplyFiltersForTaskRecorder:FilterManager": "Expected Arguments[0] to be a JSON array with DataSourceName/FieldName/Operator/Values; see filterManagerHint in this file.",
+    "SetSortsForTaskRecorder:FilterManager": "Expected Arguments[0] to be a JSON array with DataSourceName/FieldName, and a trailing human-readable direction; see filterManagerHint in this file.",
+    "ApplyFilters:FilterPane": "Expected Arguments[2] to be a JSON array of per-field filter objects; see filterManagerHint in this file.",
+};
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * D365FO's Task Recorder always captures Date-typed PropertyUserAction values as ISO
+ * (yyyy-MM-dd) -- confirmed across every recorded Date value in the library (35 distinct dates,
+ * all ISO). Some Date controls silently accept that format via form_set_control_values, but
+ * others reject it outright ("Dates must be in the format M/d/yyyy") -- confirmed live on a
+ * vendor invoice's Invoice date field, which errored on "2026-07-08" and only succeeded once
+ * reformatted to "7/8/2026". Reformatting unconditionally is safe: the target format matches the
+ * session's own Context.controlValueFormatSettings.DateFormat, which every d365-erp-mcp response
+ * already documents as the format to use.
+ */
+function formatDateForControl(value) {
+    const match = ISO_DATE.exec(value);
+    if (!match)
+        return value;
+    const [, year, month, day] = match;
+    return `${Number(month)}/${Number(day)}/${Number(year)}`;
+}
+function propertyHint(step) {
+    if (step.node.kind !== "PropertyUserAction")
+        return null;
+    const { ControlName, ControlType, Value, ListContext, UserActionType } = step.node;
+    const formattedValue = ControlType === "Date" && Value ? formatDateForControl(Value) : Value;
+    // UserActionType="Input" means the user typed/edited a value directly (confirmed live against
+    // a grid-bound field, SalesLine_SalesDeliverNow1: form_set_control_values worked directly, no
+    // filter needed). Only fall back to form_filter_grid when the action type is NOT a confirmed
+    // direct input but a ListContext is still present (unverified action types).
+    if (ListContext && UserActionType !== "Input") {
+        return {
+            tool: "form_filter_grid",
+            confidence: "medium",
+            params: { gridName: ListContext, gridColumnName: ControlName, gridColumnValue: formattedValue },
+            note: `Value was entered on a grid-bound control (UserActionType="${UserActionType}"); may be a filter rather than a cell edit.`,
+        };
+    }
+    // The recorder captures the invoice number's grid-cell name; the live Invoice number field
+    // on the vendor invoice dialog is PurchParmTable_Num (confirmed live, 2026-10-28/29 agent runs).
+    const liveControlName = ControlName === "PurchParmTable_gridParmTableNum" ? "PurchParmTable_Num" : ControlName;
+    return {
+        tool: "form_set_control_values",
+        confidence: "high",
+        params: { setControlValues: [{ controlName: liveControlName, value: formattedValue }] },
+        followUp: [
+            {
+                tool: "form_save_form",
+                note: "Confirmed live: the form reports 'has been modified and needs to be saved' after " +
+                    "form_set_control_values. Edits are not persisted until form_save_form is called.",
+            },
+        ],
+    };
+}
+/** Maps a normalized TestStep to a best-effort d365-erp-mcp tool call hint. Null for Unknown nodes. */
+export function mapStep(step) {
+    return skipHint(step) ?? menuItemHint(step) ?? commandHint(step) ?? propertyHint(step);
+}

package/dist/mcp-bridge.d.ts

@@ -0,0 +1,52 @@
+export interface BridgeConfig {
+    /** The environment's base URL, e.g. https://contoso.operations.dynamics.com */
+    environmentUrl: string;
+    tenantId: string;
+    clientId: string;
+    clientSecret: string;
+    requestTimeoutMs: number;
+}
+export interface HttpResponse {
+    status: number;
+    body: string;
+    sessionId: string | null;
+}
+/** What the bridge needs from the outside world; tests replace each one. */
+export interface BridgeDeps {
+    post(body: string, sessionId: string | null, token: string, timeoutMs: number): Promise<HttpResponse>;
+    getToken(forceRefresh: boolean): Promise<string>;
+    write(line: string): void;
+    log(text: string): void;
+    sleep(ms: number): Promise<void>;
+}
+export interface BridgeOptions {
+    requestTimeoutMs?: number;
+    /** `initialize` must answer within the client's own connect timeout (30 s in Claude Code). */
+    initializeTimeoutMs?: number;
+    /** Waits between attempts while the environment restarts (about 1 minute in total). */
+    retryDelaysMs?: number[];
+}
+interface JsonRpcMessage {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: {
+        name?: string;
+    };
+    error?: {
+        message?: string;
+    };
+    result?: unknown;
+}
+/** The JSON-RPC messages in a JSON or server-sent-events body; anything else (HTML) is skipped. */
+export declare function parseMessages(body: string): JsonRpcMessage[];
+export declare function isReplaySafe(message: JsonRpcMessage | null): boolean;
+/** The message-handling core, independent of stdio, HTTPS and MSAL. */
+export declare function createBridge(deps: BridgeDeps, options?: BridgeOptions): {
+    handle: (line: string) => Promise<void>;
+};
+/** Reads the bridge settings from the environment variables SETUP.md documents. */
+export declare function configFromEnv(env: NodeJS.ProcessEnv): BridgeConfig;
+/** `trxa mcp-bridge`: runs until stdin closes. */
+export declare function runMcpBridge(env?: NodeJS.ProcessEnv): Promise<void>;
+export {};