trxa-tool 0.1.1 → 0.2.0

package/dist/fixture-schema.d.ts

@@ -1,12 +1,52 @@
-/** Concrete input values for a TestCase's `inputs`, kept separate so the same test
- *  case can run against different data (e.g. "US company" vs "EU company") without editing it. */
+/** A named set of input values, e.g. "USMF" or "EU company", holding one slice of values per test
+ *  case it covers. Kept separate from test cases so the same test case can run against different
+ *  data without editing it, and so one data set reads as one thing even when it spans many test
+ *  cases. One fixture is one `testdata/<name>.json` file.
+ *
+ *  Suites bind to a fixture by `name` and a param (see suite-schema.ts); at run time the slice for
+ *  the test case being run is used (suite-runner.ts's `resolveInputs`). */
 export interface Fixture {
+    /** Identifier suites refer to, and the file name (`testdata/<name>.json`). Filename safe, see
+     *  `validateFixtureName`. */
+    name: string;
+    /** Short free-text description shown alongside `name` in Studio. Purely descriptive. */
+    description: string;
+    /** testCaseId -> (param name -> value). */
+    testCases: Record<string, Record<string, string>>;
+}
+/** The format before 2026-11: one file per (test case, fixture name) pair, each repeating the
+ *  fixture's name and description. Still read by the CLI (merged by name, see `mergeFixtures`) so
+ *  an existing library keeps working; `trxa migrate-fixtures` rewrites them in the current format. */
+export interface LegacyFixture {
     testCaseId: string;
     name: string;
-    /** Short free-text description shown alongside `name` in Studio's Fixtures list (e.g. "EU
-     *  vendor, small item") -- distinct from `name`, which stays a filename-safe identifier
-     *  referenced by suites' `inputBindings`. Purely descriptive; nothing resolves against it. */
     description: string;
     values: Record<string, string>;
 }
+/** Longest fixture name accepted. */
+export declare const FIXTURE_NAME_MAX_LENGTH = 64;
+/** Returns why `name` can't be a fixture name, or null when it can. A fixture's name is also its
+ *  file name, so it is limited to letters, digits, spaces, dots, underscores and hyphens, starting
+ *  with a letter or digit and not ending with a dot or space (Windows drops those silently). */
+export declare function fixtureNameProblem(name: string): string | null;
+/** True when `value` looks like the pre-2026-11 one-test-case-per-file format. */
+export declare function isLegacyFixture(value: unknown): boolean;
 export declare function validateFixture(value: unknown): Fixture;
+export declare function validateLegacyFixture(value: unknown): LegacyFixture;
+/** Reads either format. A legacy file becomes a Fixture covering its one test case. Its name is
+ *  not checked against `fixtureNameProblem`, since legacy names were never limited and still have
+ *  to load; `trxa migrate-fixtures` reports a name that can't become a file name. */
+export declare function validateFixtureFile(value: unknown): Fixture;
+/** Merges fixtures that share a name (case-insensitively, since file names on Windows are) into
+ *  one each, in input order. The first non-empty description wins. Two sources holding values for
+ *  the same test case under the same name is ambiguous, so it throws, naming both sources. */
+export declare function mergeFixtures(sources: {
+    source: string;
+    fixture: Fixture;
+}[]): {
+    fixture: Fixture;
+    sources: string[];
+}[];
+/** Writes a fixture the way every tool writes one, with test cases in a stable order so a saved
+ *  file diffs cleanly. */
+export declare function serializeFixture(fixture: Fixture): string;

package/dist/fixture-schema.js

@@ -1,3 +1,19 @@
+/** Longest fixture name accepted. */
+export const FIXTURE_NAME_MAX_LENGTH = 64;
+const FIXTURE_NAME_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9 ._-]*[A-Za-z0-9_-])?$/;
+/** Returns why `name` can't be a fixture name, or null when it can. A fixture's name is also its
+ *  file name, so it is limited to letters, digits, spaces, dots, underscores and hyphens, starting
+ *  with a letter or digit and not ending with a dot or space (Windows drops those silently). */
+export function fixtureNameProblem(name) {
+    if (name.length === 0)
+        return "must not be empty";
+    if (name.length > FIXTURE_NAME_MAX_LENGTH)
+        return `must be at most ${FIXTURE_NAME_MAX_LENGTH} characters`;
+    if (!FIXTURE_NAME_PATTERN.test(name)) {
+        return "may only use letters, digits, spaces, dots, underscores and hyphens, starting with a letter or digit and not ending with a dot or space";
+    }
+    return null;
+}
 function fail(field, reason) {
     throw new Error(`Invalid Fixture: ${field} ${reason}`);
 }
@@ -5,24 +21,92 @@ function assertString(value, field) {
     if (typeof value !== "string" || value.length === 0)
         fail(field, "must be a non-empty string");
 }
+function assertStringMap(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(field, "must be an object mapping param names to string values");
+    }
+    for (const [key, val] of Object.entries(value)) {
+        if (typeof val !== "string")
+            fail(`${field}.${key}`, "must be a string");
+    }
+}
+/** True when `value` looks like the pre-2026-11 one-test-case-per-file format. */
+export function isLegacyFixture(value) {
+    return typeof value === "object" && value !== null && "testCaseId" in value && !("testCases" in value);
+}
 export function validateFixture(value) {
     if (typeof value !== "object" || value === null)
         fail("fixture", "must be an object");
     const v = value;
-    assertString(v.testCaseId, "testCaseId");
     assertString(v.name, "name");
-    assertString(v.description, "description");
-    if (typeof v.values !== "object" || v.values === null || Array.isArray(v.values)) {
-        fail("values", "must be an object mapping param names to string values");
+    const problem = fixtureNameProblem(v.name);
+    if (problem)
+        fail("name", problem);
+    if (typeof v.description !== "string")
+        fail("description", "must be a string");
+    if (typeof v.testCases !== "object" || v.testCases === null || Array.isArray(v.testCases)) {
+        fail("testCases", "must be an object mapping test case ids to their values");
     }
-    for (const [key, val] of Object.entries(v.values)) {
-        if (typeof val !== "string")
-            fail(`values.${key}`, "must be a string");
+    const testCases = {};
+    for (const [testCaseId, values] of Object.entries(v.testCases)) {
+        if (testCaseId.length === 0)
+            fail("testCases", "must not contain an empty test case id");
+        assertStringMap(values, `testCases.${testCaseId}`);
+        testCases[testCaseId] = { ...values };
     }
-    return {
-        testCaseId: v.testCaseId,
-        name: v.name,
-        description: v.description,
-        values: v.values,
-    };
+    return { name: v.name, description: v.description, testCases };
+}
+export function validateLegacyFixture(value) {
+    if (typeof value !== "object" || value === null)
+        fail("fixture", "must be an object");
+    const v = value;
+    assertString(v.testCaseId, "testCaseId");
+    assertString(v.name, "name");
+    if (typeof v.description !== "string")
+        fail("description", "must be a string");
+    assertStringMap(v.values, "values");
+    return { testCaseId: v.testCaseId, name: v.name, description: v.description, values: { ...v.values } };
+}
+/** Reads either format. A legacy file becomes a Fixture covering its one test case. Its name is
+ *  not checked against `fixtureNameProblem`, since legacy names were never limited and still have
+ *  to load; `trxa migrate-fixtures` reports a name that can't become a file name. */
+export function validateFixtureFile(value) {
+    if (!isLegacyFixture(value))
+        return validateFixture(value);
+    const legacy = validateLegacyFixture(value);
+    return { name: legacy.name, description: legacy.description, testCases: { [legacy.testCaseId]: legacy.values } };
+}
+/** Merges fixtures that share a name (case-insensitively, since file names on Windows are) into
+ *  one each, in input order. The first non-empty description wins. Two sources holding values for
+ *  the same test case under the same name is ambiguous, so it throws, naming both sources. */
+export function mergeFixtures(sources) {
+    const merged = new Map();
+    for (const { source, fixture } of sources) {
+        const key = fixture.name.toLowerCase();
+        let entry = merged.get(key);
+        if (!entry) {
+            entry = { fixture: { name: fixture.name, description: fixture.description, testCases: {} }, sources: [], slices: new Map() };
+            merged.set(key, entry);
+        }
+        if (!entry.fixture.description && fixture.description)
+            entry.fixture.description = fixture.description;
+        entry.sources.push(source);
+        for (const [testCaseId, values] of Object.entries(fixture.testCases)) {
+            const previous = entry.slices.get(testCaseId);
+            if (previous) {
+                throw new Error(`Fixture "${fixture.name}" has values for test case "${testCaseId}" in both ${previous} and ${source}. Keep one of them.`);
+            }
+            entry.slices.set(testCaseId, source);
+            entry.fixture.testCases[testCaseId] = { ...values };
+        }
+    }
+    return [...merged.values()].map(({ fixture, sources }) => ({ fixture, sources }));
+}
+/** Writes a fixture the way every tool writes one, with test cases in a stable order so a saved
+ *  file diffs cleanly. */
+export function serializeFixture(fixture) {
+    const testCases = {};
+    for (const id of Object.keys(fixture.testCases).sort((a, b) => a.localeCompare(b)))
+        testCases[id] = fixture.testCases[id];
+    return JSON.stringify({ name: fixture.name, description: fixture.description, testCases }, null, 2) + "\n";
 }

package/dist/fixture-store.d.ts

@@ -0,0 +1,37 @@
+import { type Fixture } from "./fixture-schema.js";
+export interface FixtureFolder {
+    /** Every fixture in the folder, with legacy files merged into the fixture they name. */
+    fixtures: {
+        fixture: Fixture;
+        files: string[];
+    }[];
+    /** File names (with extension) still in the pre-2026-11 one-test-case format. */
+    legacyFiles: string[];
+    /** Files that could not be read as a fixture at all. */
+    invalid: {
+        file: string;
+        error: string;
+    }[];
+}
+/** A missing folder reads as empty: a suite that binds no fixture doesn't need one to exist. */
+export declare function readFixtureFolder(dir: string): Promise<FixtureFolder>;
+/** A fixture is in its final shape when it is exactly one current format file named after it.
+ *  Anything else (legacy files, or a file named differently from the fixture inside it) is what
+ *  `migrateFixtureFolder` rewrites. */
+export declare function needsMigration(fixture: Fixture, files: string[], legacyFiles: string[]): boolean;
+export interface MigrationResult {
+    /** File written (`<name>.json`) and the files merged into it. */
+    written: {
+        file: string;
+        fixture: string;
+        from: string[];
+    }[];
+    /** Legacy files removed after their values were written. */
+    removed: string[];
+}
+/** Rewrites every legacy file in `dir` into one `<name>.json` per fixture, merging into a current
+ *  format file of that name when one exists, then removes the legacy files. Everything is checked
+ *  before anything is written, so a conflict or an unusable name leaves the folder untouched. */
+export declare function migrateFixtureFolder(dir: string, options?: {
+    dryRun?: boolean;
+}): Promise<MigrationResult>;

package/dist/fixture-store.js

@@ -0,0 +1,75 @@
+/** Reading and migrating a fixtures folder (`testdata/`), shared by the CLI and Studio's server so
+ *  both see the same fixtures and the same migration. */
+import { readdir, readFile, writeFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import { fixtureNameProblem, isLegacyFixture, mergeFixtures, serializeFixture, validateFixtureFile, } from "./fixture-schema.js";
+/** A missing folder reads as empty: a suite that binds no fixture doesn't need one to exist. */
+export async function readFixtureFolder(dir) {
+    let entries;
+    try {
+        entries = (await readdir(dir)).filter((f) => f.endsWith(".json")).sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return { fixtures: [], legacyFiles: [], invalid: [] };
+    }
+    const sources = [];
+    const legacyFiles = [];
+    const invalid = [];
+    for (const file of entries) {
+        try {
+            const raw = JSON.parse(await readFile(path.join(dir, file), "utf-8"));
+            if (isLegacyFixture(raw))
+                legacyFiles.push(file);
+            sources.push({ source: file, fixture: validateFixtureFile(raw) });
+        }
+        catch (err) {
+            invalid.push({ file, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // Files in the current format come first, so a fixture's own description wins over a legacy
+    // file's when both exist.
+    sources.sort((a, b) => Number(legacyFiles.includes(a.source)) - Number(legacyFiles.includes(b.source)));
+    const fixtures = mergeFixtures(sources).map(({ fixture, sources }) => ({ fixture, files: sources }));
+    return { fixtures, legacyFiles, invalid };
+}
+/** A fixture is in its final shape when it is exactly one current format file named after it.
+ *  Anything else (legacy files, or a file named differently from the fixture inside it) is what
+ *  `migrateFixtureFolder` rewrites. */
+export function needsMigration(fixture, files, legacyFiles) {
+    if (files.some((f) => legacyFiles.includes(f)))
+        return true;
+    return files.length !== 1 || files[0].toLowerCase() !== `${fixture.name}.json`.toLowerCase();
+}
+/** Rewrites every legacy file in `dir` into one `<name>.json` per fixture, merging into a current
+ *  format file of that name when one exists, then removes the legacy files. Everything is checked
+ *  before anything is written, so a conflict or an unusable name leaves the folder untouched. */
+export async function migrateFixtureFolder(dir, options = {}) {
+    const folder = await readFixtureFolder(dir);
+    if (folder.invalid.length > 0) {
+        throw new Error(`Fix or remove these files first: ${folder.invalid.map((i) => `${i.file} (${i.error})`).join("; ")}`);
+    }
+    const plan = [];
+    for (const { fixture, files } of folder.fixtures) {
+        if (!needsMigration(fixture, files, folder.legacyFiles))
+            continue;
+        const problem = fixtureNameProblem(fixture.name);
+        if (problem) {
+            throw new Error(`Fixture name "${fixture.name}" (in ${files.join(", ")}) can't be used as a file name: it ${problem}. Rename it first.`);
+        }
+        const file = `${fixture.name}.json`;
+        plan.push({ file, fixture, from: files });
+    }
+    // Every source merged into <name>.json is removed afterwards, except <name>.json itself, which
+    // is overwritten in place (compared case-insensitively, as Windows does).
+    const result = {
+        written: plan.map(({ file, fixture, from }) => ({ file, fixture: fixture.name, from })),
+        removed: plan.flatMap(({ file, from }) => from.filter((f) => f.toLowerCase() !== file.toLowerCase())),
+    };
+    if (options.dryRun)
+        return result;
+    for (const { file, fixture } of plan)
+        await writeFile(path.join(dir, file), serializeFixture(fixture), "utf-8");
+    for (const file of result.removed)
+        await unlink(path.join(dir, file));
+    return result;
+}

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { readFile, writeFile, readdir, mkdir, unlink } from "node:fs/promises";
+import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
+import { runMcpBridge } from "./mcp-bridge.js";
 import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 import path from "node:path";
@@ -10,7 +11,8 @@ import { analyzeLibrary } from "./analyze.js";
 import { toCsv } from "./csv.js";
 import { suggestInputs } from "./suggest-inputs.js";
 import { validateTestCase } from "./testcase-schema.js";
-import { validateFixture } from "./fixture-schema.js";
+import { isLegacyFixture, validateFixtureFile } from "./fixture-schema.js";
+import { migrateFixtureFolder, readFixtureFolder } from "./fixture-store.js";
 import { validateTestSuite } from "./suite-schema.js";
 import { validateTestPlan } from "./plan-schema.js";
 import { topologicalOrder, resolveInputs, nextStep } from "./suite-runner.js";
@@ -70,28 +72,19 @@ async function loadTestCaseFile(testcasesDir, testCaseId) {
     return validateTestCase(raw);
 }
 /** `--fixtures-dir` is optional at the CLI level (see `resolve-next`'s usage) -- if omitted, this
- *  function is never called at all and `fixtures` is just `[]`. This catch only fires when the
- *  flag *was* passed but the directory doesn't exist, and it's deliberately treated the same as
- *  "empty directory" rather than a hard error: a suite that binds nothing via `fixture` kind
- *  doesn't need one to exist. The tradeoff is a mistyped `--fixtures-dir` path silently produces
- *  zero fixtures instead of an error naming the bad path -- the first symptom a reviewer sees is
- *  `suite-runner.ts`'s later, less specific "no fixture named X found". */
+ *  function is never called at all and `fixtures` is just `[]`. A folder that doesn't exist reads
+ *  as empty rather than a hard error (see fixture-store.ts): a suite that binds nothing via
+ *  `fixture` kind doesn't need one to exist. The tradeoff is a mistyped `--fixtures-dir` path
+ *  silently produces zero fixtures instead of an error naming the bad path -- the first symptom a
+ *  reviewer sees is `suite-runner.ts`'s later, less specific "no fixture named X found". Files in
+ *  the pre-2026-11 one-test-case format are merged into the fixture they name, so an unmigrated
+ *  library still runs. */
 async function loadFixtures(fixturesDir) {
-    let entries;
-    try {
-        entries = await readdir(fixturesDir);
-    }
-    catch {
-        return [];
-    }
-    const fixtures = [];
-    for (const entry of entries) {
-        if (!entry.endsWith(".json"))
-            continue;
-        const raw = JSON.parse(await readFile(path.join(fixturesDir, entry), "utf-8"));
-        fixtures.push(validateFixture(raw));
+    const folder = await readFixtureFolder(fixturesDir);
+    if (folder.invalid.length > 0) {
+        throw new Error(`Invalid fixture file ${folder.invalid[0].file}: ${folder.invalid[0].error}`);
     }
-    return fixtures;
+    return folder.fixtures.map((f) => f.fixture);
 }
 async function loadSuite(suitePath) {
     const raw = JSON.parse(await readFile(suitePath, "utf-8"));
@@ -134,8 +127,26 @@ async function cmdValidateFixture(args) {
     if (!filePath)
         throw new Error("Usage: trxa validate-fixture <fixture.json>");
     const raw = JSON.parse(await readFile(filePath, "utf-8"));
-    const fixture = validateFixture(raw);
-    console.error(`OK: "${fixture.name}" is a valid fixture for test case "${fixture.testCaseId}"`);
+    const fixture = validateFixtureFile(raw);
+    const ids = Object.keys(fixture.testCases);
+    const legacy = isLegacyFixture(raw) ? " (old one test case per file format; run `trxa migrate-fixtures` to update it)" : "";
+    console.error(`OK: "${fixture.name}" is a valid fixture with values for ${ids.length} test case(s): ${ids.join(", ")}${legacy}`);
+}
+async function cmdMigrateFixtures(args) {
+    const [dir, ...rest] = args;
+    if (!dir)
+        throw new Error("Usage: trxa migrate-fixtures <testdata-dir> [--dry-run]");
+    const dryRun = rest.includes("--dry-run");
+    const result = await migrateFixtureFolder(dir, { dryRun });
+    if (result.written.length === 0) {
+        console.error("Nothing to migrate: every fixture is already one file named after it.");
+        return;
+    }
+    const verb = dryRun ? "Would write" : "Wrote";
+    for (const w of result.written)
+        console.error(`${verb} ${w.file} (fixture "${w.fixture}") from ${w.from.join(", ")}`);
+    if (result.removed.length > 0)
+        console.error(`${dryRun ? "Would remove" : "Removed"}: ${result.removed.join(", ")}`);
 }
 async function cmdValidateSuite(args) {
     const [filePath] = args;
@@ -189,21 +200,33 @@ async function cmdInitSkill(args) {
         `(${SKILL_INSTALL_TARGETS.map((t) => t.relativePath).join(", ")}) -- each tool will pick it up ` +
         `automatically the next time it runs in this project.`);
 }
+/** Started by an agent CLI as its `d365-erp-mcp` server; settings come from environment variables. */
+async function cmdMcpBridge() {
+    try {
+        await runMcpBridge(process.env);
+    }
+    catch (err) {
+        // The agent shows this in its MCP server log; a stack trace would bury the setting to fix.
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+}
 async function cmdInitRun(args) {
     const [suitePath, ...rest] = args;
     const outPath = flagValue(rest, "-o");
     if (!suitePath || !outPath) {
-        throw new Error("Usage: trxa init-run <suite.json> -o testruns/<suiteId>-<runId>.json");
+        throw new Error('Usage: trxa init-run <suite.json> -o testruns/<suiteId>-<runId>.json [--name "<run name>"]');
     }
     const suite = await loadSuite(suitePath);
-    const testRun = await initTestRun(suite, outPath);
+    const name = flagValue(rest, "--name") ?? undefined;
+    const testRun = await initTestRun(suite, outPath, { name });
     console.error(`Initialized test run for suite "${suite.id}" (${Object.keys(testRun.results).length} test cases, all pending) at ${outPath}`);
 }
 async function cmdInitPlanRun(args) {
     const [planPath, ...rest] = args;
     const outDir = flagValue(rest, "-o");
     if (!planPath || !outDir) {
-        throw new Error("Usage: trxa init-plan-run <plan.json> -o runs/");
+        throw new Error('Usage: trxa init-plan-run <plan.json> -o runs/ [--name "<run name>"]');
     }
     const plan = await loadPlan(planPath);
     const planDir = path.dirname(planPath);
@@ -211,7 +234,8 @@ async function cmdInitPlanRun(args) {
         const suite = await loadSuite(path.resolve(planDir, entry.suitePath));
         return { id: suite.id, name: suite.name };
     }));
-    const { planRun, filePath } = await initPlanRun(plan.id, suites, outDir);
+    const name = flagValue(rest, "--name") ?? undefined;
+    const { planRun, filePath } = await initPlanRun(plan.id, suites, outDir, name);
     console.error(`Initialized plan run "${planRun.id}" for plan "${plan.id}" at ${filePath}`);
     console.log(JSON.stringify(planRun, null, 2));
 }
@@ -502,7 +526,7 @@ async function launchDetachedScript(scriptPath, cwd) {
         const child = spawn("/bin/sh", [scriptPath], { cwd, detached: true, stdio: "ignore" });
         child.unref();
         if (!child.pid)
-            throw new Error("Failed to start trxa-tool Studio (no PID returned)");
+            throw new Error("Failed to start TRXA Studio (no PID returned)");
         return child.pid;
     }
     const psCommand = `$p = Start-Process -FilePath 'cmd.exe' -ArgumentList '/c','${scriptPath}' ` +
@@ -518,7 +542,7 @@ async function launchDetachedScript(scriptPath, cwd) {
         ps.on("exit", (code) => {
             const pid = Number(out.trim());
             if (code !== 0 || !Number.isInteger(pid)) {
-                reject(new Error(`Failed to launch trxa-tool Studio via PowerShell (exit ${code}): ${out.trim()}`));
+                reject(new Error(`Failed to launch TRXA Studio via PowerShell (exit ${code}): ${out.trim()}`));
             }
             else {
                 resolve(pid);
@@ -558,7 +582,7 @@ async function cmdStudioStart(repoRoot) {
     const studioUrl = packagedServer ? `http://127.0.0.1:${process.env.STUDIO_SERVER_PORT ?? 4321}/` : STUDIO_URL;
     const existingPid = await readStudioPid(pidFile);
     if (existingPid !== null && isProcessAlive(existingPid)) {
-        console.error(`trxa-tool Studio is already running (PID ${existingPid}). Opening ${studioUrl} ...`);
+        console.error(`TRXA Studio is already running (PID ${existingPid}). Opening ${studioUrl} ...`);
         openBrowser(studioUrl);
         return;
     }
@@ -589,13 +613,13 @@ async function cmdStudioStart(repoRoot) {
     await writeFile(pidFile, String(pid), "utf-8");
     const ready = await waitForServer(studioUrl, 20_000);
     if (ready) {
-        console.error(`trxa-tool Studio is running in the background (PID ${pid}).\n` +
+        console.error(`TRXA Studio is running in the background (PID ${pid}).\n` +
             `  UI:   ${studioUrl}\n` +
             `  Logs: ${logFile}\n` +
             `  Stop: trxa studio stop`);
     }
     else {
-        console.error(`trxa-tool Studio (PID ${pid}) is taking longer than expected to come up -- check ${logFile}.\n` +
+        console.error(`TRXA Studio (PID ${pid}) is taking longer than expected to come up -- check ${logFile}.\n` +
             `  Opening ${studioUrl} anyway; refresh if it's not ready yet.\n` +
             `  Stop: trxa studio stop`);
     }
@@ -605,11 +629,11 @@ async function cmdStudioStop() {
     const pidFile = path.join(STUDIO_RUN_DIR, "pid");
     const pid = await readStudioPid(pidFile);
     if (pid === null) {
-        console.error("trxa-tool Studio doesn't appear to be running (no PID file found).");
+        console.error("TRXA Studio doesn't appear to be running (no PID file found).");
         return;
     }
     if (!isProcessAlive(pid)) {
-        console.error(`trxa-tool Studio isn't running (stale PID ${pid}) -- cleaning up.`);
+        console.error(`TRXA Studio isn't running (stale PID ${pid}) -- cleaning up.`);
         await unlink(pidFile).catch(() => { });
         return;
     }
@@ -631,7 +655,7 @@ async function cmdStudioStop() {
         }
     }
     await unlink(pidFile).catch(() => { });
-    console.error(`Stopped trxa-tool Studio (was PID ${pid}).`);
+    console.error(`Stopped TRXA Studio (was PID ${pid}).`);
 }
 /** Launches (or stops) the Studio server+client, detached and backgrounded so `trxa studio`
  *  returns control immediately and auto-opens the browser. Delegates to the root `npm run studio`
@@ -665,6 +689,12 @@ const COMMAND_GROUPS = [
         commands: [
             { name: "validate-testcase", usage: "<testcase.json>", summary: "Validate a Test Case file", handler: cmdValidateTestCase },
             { name: "validate-fixture", usage: "<fixture.json>", summary: "Validate a Fixture file", handler: cmdValidateFixture },
+            {
+                name: "migrate-fixtures",
+                usage: "<testdata-dir> [--dry-run]",
+                summary: "Merge one-test-case fixture files into one file per fixture",
+                handler: cmdMigrateFixtures,
+            },
             {
                 name: "validate-suite",
                 usage: "<suite.json>",
@@ -689,6 +719,12 @@ const COMMAND_GROUPS = [
                 summary: "Copy the replay-trxa-testplan skill into this project for Claude Code and Codex to pick up",
                 handler: cmdInitSkill,
             },
+            {
+                name: "mcp-bridge",
+                usage: "",
+                summary: "Connect an agent to a D365 environment's MCP server (started by the agent; see SETUP.md)",
+                handler: cmdMcpBridge,
+            },
         ],
     },
     {
@@ -696,14 +732,14 @@ const COMMAND_GROUPS = [
         commands: [
             {
                 name: "init-plan-run",
-                usage: "<plan.json> -o runs/",
-                summary: "Create a new PlanRun record for a plan, auto-generating its id",
+                usage: '<plan.json> -o runs/ [--name "<run name>"]',
+                summary: "Create a new PlanRun record for a plan, auto-generating its id; --name labels the run",
                 handler: cmdInitPlanRun,
             },
             {
                 name: "init-run",
-                usage: "<suite.json> -o testruns/<suiteId>-<runId>.json",
-                summary: "Create a new Test Run file for a suite, all test cases pending",
+                usage: '<suite.json> -o testruns/<suiteId>-<runId>.json [--name "<run name>"]',
+                summary: "Create a new Test Run file for a suite, all test cases pending; --name labels the run",
                 handler: cmdInitRun,
             },
             {

package/dist/mapping.js

@@ -371,10 +371,13 @@ function propertyHint(step) {
             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: ControlName, value: formattedValue }] },
+        params: { setControlValues: [{ controlName: liveControlName, value: formattedValue }] },
         followUp: [
             {
                 tool: "form_save_form",

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 {};