trxa-tool 0.0.0-stage → 0.2.0

package/dist/bpm.js

@@ -0,0 +1,60 @@
+import JSZip from "jszip";
+import { XMLParser } from "fast-xml-parser";
+function asArray(v) {
+    if (v === undefined)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+function parseProcessStepXml(xml) {
+    const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "" });
+    const doc = parser.parse(xml);
+    const tasks = asArray(doc.Activities?.Task);
+    return {
+        tasks: tasks.map((t) => ({
+            id: String(t.Id ?? ""),
+            aotName: String(t.AOTName ?? ""),
+            objectType: String(t.ObjectType ?? ""),
+            configurationKey: String(t.ConfigurationKey ?? ""),
+            layer: String(t.Layer ?? ""),
+            model: String(t.Model ?? ""),
+            sequence: Number(t.Sequence ?? 0),
+            security: asArray(t.Permissions?.Security).map((s) => ({
+                roleName: String(s.RoleName ?? ""),
+                roleDisplayName: String(s.RoleDisplayName ?? ""),
+                dutyName: String(s.DutyName ?? ""),
+                dutyDisplayName: String(s.DutyDisplayName ?? ""),
+                privilegeName: String(s.PrivilegeName ?? ""),
+                privilegeDisplayName: String(s.PrivilegeDisplayName ?? ""),
+                accessLevel: String(s.AccessLevel ?? ""),
+                isValidRole: String(s.IsValidRole ?? "").toLowerCase() === "true",
+            })),
+            connectsTo: asArray(t.Connections?.Connection).map((c) => String(c.Target ?? "")),
+        })),
+    };
+}
+/** Parses the nested BPMPackage.ax7bpm bytes extracted from a .axtr file. Returns null if absent. */
+export async function parseBpmPackage(bytes) {
+    if (!bytes)
+        return null;
+    const zip = await JSZip.loadAsync(bytes);
+    // The backslash variant is defensive, not confirmed live: every recording checked so far uses
+    // "/", but zip entry names are just stored strings (no path-separator normalization is
+    // guaranteed across the tools that can produce a BPMPackage.ax7bpm), so this is here in case a
+    // Windows-authored zip ever stores "Recording\ProcessStep.xml" literally instead.
+    const entry = zip.file("Recording/ProcessStep.xml") ?? zip.file("Recording\\ProcessStep.xml") ?? null;
+    if (!entry)
+        return null;
+    const xml = await entry.async("string");
+    return parseProcessStepXml(xml);
+}
+/** Every distinct privilege that appears across all tasks -- a starting point for a security preflight check. */
+export function distinctPrivileges(pkg) {
+    const set = new Set();
+    for (const task of pkg.tasks) {
+        for (const sec of task.security) {
+            if (sec.privilegeName)
+                set.add(sec.privilegeName);
+        }
+    }
+    return [...set];
+}

package/dist/build-test-script.d.ts

@@ -0,0 +1,24 @@
+import { type TestScript } from "./normalize.js";
+/** Mechanics only, no hints -- the raw shape mapStep/suggestInputs operate on. */
+export declare function loadTestScript(axtrPath: string): Promise<TestScript>;
+/** Full `testscript.json` shape: mechanics plus per-step hints and security info. */
+export declare function buildTestScript(axtrPath: string): Promise<{
+    name: string;
+    canonicalId: string;
+    description: string;
+    steps: {
+        sequence: number;
+        description: string;
+        formName: string | null;
+        nodeType: "Scope" | "MenuItemUserAction" | "CommandUserAction" | "PropertyUserAction" | "Unknown";
+        node: import("./schema.js").RecordingNode;
+        hint: import("./mapping.js").McpToolHint | null;
+    }[];
+    security: {
+        requiredPrivileges: string[];
+        formsVisited: {
+            aotName: string;
+            objectType: string;
+        }[];
+    } | null;
+}>;

package/dist/build-test-script.js

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { extractAxtr } from "./extract.js";
+import { parseRecordingXml } from "./parse.js";
+import { normalizeRecording } from "./normalize.js";
+import { mapStep } from "./mapping.js";
+import { parseBpmPackage, distinctPrivileges } from "./bpm.js";
+/** Mechanics only, no hints -- the raw shape mapStep/suggestInputs operate on. */
+export async function loadTestScript(axtrPath) {
+    const bytes = await readFile(axtrPath);
+    const extracted = await extractAxtr(bytes);
+    const recording = parseRecordingXml(extracted.recordingXml);
+    return normalizeRecording(recording);
+}
+/** Full `testscript.json` shape: mechanics plus per-step hints and security info. */
+export async function buildTestScript(axtrPath) {
+    const bytes = await readFile(axtrPath);
+    const extracted = await extractAxtr(bytes);
+    const recording = parseRecordingXml(extracted.recordingXml);
+    const script = normalizeRecording(recording);
+    const bpm = await parseBpmPackage(extracted.bpmPackageBytes);
+    return {
+        name: script.name,
+        canonicalId: script.canonicalId,
+        description: script.description,
+        steps: script.steps.map((step) => ({
+            sequence: step.sequence,
+            description: step.description,
+            formName: step.formName,
+            nodeType: step.node.kind,
+            node: step.node,
+            hint: mapStep(step),
+        })),
+        security: bpm
+            ? {
+                requiredPrivileges: distinctPrivileges(bpm),
+                formsVisited: bpm.tasks.map((t) => ({ aotName: t.aotName, objectType: t.objectType })),
+            }
+            : null,
+    };
+}

package/dist/csv.d.ts

@@ -0,0 +1 @@
+export declare function toCsv(header: string[], rows: string[][]): string;

package/dist/csv.js

@@ -0,0 +1,11 @@
+/** Minimal RFC4180 CSV writer -- no dependency needed for the handful of columns this repo emits. */
+function escapeCell(value) {
+    if (/[",\r\n]/.test(value)) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+export function toCsv(header, rows) {
+    const lines = [header, ...rows].map((row) => row.map(escapeCell).join(","));
+    return lines.join("\r\n") + "\r\n";
+}

package/dist/extract.d.ts

@@ -0,0 +1,14 @@
+export declare const RECORDING_ENTRY = "Recording.xml";
+export declare const RESOURCE_ENTRY = "recording_resource.xml";
+export declare const BPM_ENTRY = "BPMPackage.ax7bpm";
+export interface ExtractedAxtr {
+    recordingXml: string;
+    resourceXml: string | null;
+    /** Raw bytes of the nested BPMPackage.ax7bpm zip, if present. Parsed separately by bpm.ts. */
+    bpmPackageBytes: Buffer | null;
+}
+/**
+ * Unzips a .axtr file (confirmed to be a plain ZIP via its PK\x03\x04 header) and pulls out
+ * the entries D365FO's own UserSecGovTaskRecorderUtil::GetRecordingFromPackage reads.
+ */
+export declare function extractAxtr(fileBytes: Buffer): Promise<ExtractedAxtr>;

package/dist/extract.js

@@ -0,0 +1,34 @@
+import JSZip from "jszip";
+export const RECORDING_ENTRY = "Recording.xml";
+export const RESOURCE_ENTRY = "recording_resource.xml";
+export const BPM_ENTRY = "BPMPackage.ax7bpm";
+/**
+ * Unzips a .axtr file (confirmed to be a plain ZIP via its PK\x03\x04 header) and pulls out
+ * the entries D365FO's own UserSecGovTaskRecorderUtil::GetRecordingFromPackage reads.
+ */
+export async function extractAxtr(fileBytes) {
+    const zip = await JSZip.loadAsync(fileBytes);
+    const recordingEntry = findEntry(zip, RECORDING_ENTRY);
+    if (!recordingEntry) {
+        throw new Error(`.axtr package does not contain a ${RECORDING_ENTRY} entry`);
+    }
+    const resourceEntry = findEntry(zip, RESOURCE_ENTRY);
+    const bpmEntry = findEntry(zip, BPM_ENTRY);
+    return {
+        recordingXml: await recordingEntry.async("string"),
+        resourceXml: resourceEntry ? await resourceEntry.async("string") : null,
+        bpmPackageBytes: bpmEntry ? await bpmEntry.async("nodebuffer") : null,
+    };
+}
+/** Case-insensitive fallback is defensive, not confirmed live: every `.axtr` checked so far uses
+ *  the exact casing in `RECORDING_ENTRY`/`RESOURCE_ENTRY`/`BPM_ENTRY` above. Zip entry names are
+ *  just stored strings with no case-folding guarantee across whatever tool produced the archive,
+ *  so this exists in case one ever doesn't match exactly -- same rationale as `bpm.ts`'s backslash
+ *  path fallback. */
+function findEntry(zip, name) {
+    const exact = zip.file(name);
+    if (exact)
+        return exact;
+    const match = Object.values(zip.files).find((f) => !f.dir && f.name.toLowerCase() === name.toLowerCase());
+    return match ?? null;
+}

package/dist/fixture-schema.d.ts

@@ -0,0 +1,52 @@
+/** 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;
+    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

@@ -0,0 +1,112 @@
+/** 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}`);
+}
+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.name, "name");
+    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");
+    }
+    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 { 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.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { loadTestScript, buildTestScript } from "./build-test-script.js";
+export { loadTestScript, buildTestScript };