trxa-tool 0.0.0-stage → 0.2.0

package/dist/mcp-bridge.js

@@ -0,0 +1,290 @@
+/**
+ * `trxa mcp-bridge`: a stdio MCP server that forwards every message to a Dynamics 365 finance and
+ * operations environment's MCP endpoint (`<environment URL>/mcp`, streamable HTTP), signing in as a
+ * Microsoft Entra app registration (client credentials).
+ *
+ * Agent CLIs (GitHub Copilot CLI, Claude Code) start it as a local server named `d365-erp-mcp`.
+ * Neither CLI is on the environment's default "Allowed MCP clients" list, and a replay runs
+ * unattended, so a registered app with its own D365 user is the setup SETUP.md documents.
+ *
+ * Besides forwarding, it keeps a long replay alive across environment restarts:
+ * - every request has a timeout, and connections are never reused, so a recycled server can't
+ *   leave a request hanging on a dead socket;
+ * - when the server loses the session, it opens a new one by replaying the client's `initialize`
+ *   handshake, then retries;
+ * - it replays a request only when that is safe: the server rejected it without running it
+ *   (session not found, 401, 408/429/502/503/504), or the tool only reads. A tool call that timed
+ *   out may have run, so it is answered with an error instead of being replayed;
+ * - every request with an id gets an answer, a JSON-RPC error when all else fails.
+ *
+ * stdout carries only JSON-RPC messages; diagnostics go to stderr.
+ */
+import https from "node:https";
+import readline from "node:readline";
+const TRANSIENT_STATUS = new Set([408, 429, 502, 503, 504]);
+/** Methods that only read, so replaying them after a timeout is harmless. */
+const SAFE_METHODS = new Set(["initialize", "ping", "tools/list", "resources/list", "resources/templates/list", "prompts/list"]);
+/** Tools that only read. */
+const READ_ONLY_TOOL = /^(get_current_user|data_find_|data_get_|form_find_|api_find_)/;
+const SESSION_LOST = /session.*(could not be found|not found|expired)/i;
+/** The JSON-RPC messages in a JSON or server-sent-events body; anything else (HTML) is skipped. */
+export function parseMessages(body) {
+    const messages = [];
+    for (const raw of (body || "").split("\n")) {
+        const line = raw.startsWith("data: ") ? raw.slice(6) : raw;
+        if (!line.trim() || line.startsWith(":") || line.startsWith("event:") || line.startsWith("id:"))
+            continue;
+        try {
+            messages.push(JSON.parse(line));
+        }
+        catch {
+            // not JSON
+        }
+    }
+    return messages;
+}
+export function isReplaySafe(message) {
+    if (!message?.method)
+        return false;
+    if (SAFE_METHODS.has(message.method))
+        return true;
+    return message.method === "tools/call" && READ_ONLY_TOOL.test(message.params?.name ?? "");
+}
+function isSessionLost(response) {
+    if (response.status === 404)
+        return true;
+    if (response.status >= 400)
+        return SESSION_LOST.test(response.body || "");
+    // A 2xx counts only when it carries a JSON-RPC *error* about the session: a tool result that
+    // merely mentions those words must not trigger a replay.
+    return parseMessages(response.body).some((m) => m.error && SESSION_LOST.test(m.error.message || ""));
+}
+/** The message-handling core, independent of stdio, HTTPS and MSAL. */
+export function createBridge(deps, options = {}) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? 90000;
+    const initializeTimeoutMs = options.initializeTimeoutMs ?? 25000;
+    const retryDelaysMs = options.retryDelaysMs ?? [5000, 15000, 30000];
+    let sessionId = null;
+    let initializeLine = null; // replayed to open a new session
+    let initializedLine = null; // notifications/initialized, replayed after it
+    let reopening = null; // shared, so concurrent requests reopen only once
+    async function post(body, session, timeoutMs) {
+        return deps.post(body, session, await deps.getToken(false), timeoutMs);
+    }
+    function reopenSession() {
+        if (!initializeLine)
+            return Promise.reject(new Error("no initialize request to replay"));
+        if (!reopening) {
+            const init = initializeLine;
+            reopening = (async () => {
+                deps.log(`opening a new session (previous: ${sessionId || "none"})`);
+                sessionId = null;
+                const response = await post(init, null, initializeTimeoutMs);
+                if (response.status < 200 || response.status >= 300 || !response.sessionId) {
+                    throw new Error(`initialize returned HTTP ${response.status}`);
+                }
+                sessionId = response.sessionId;
+                if (initializedLine)
+                    await post(initializedLine, sessionId, requestTimeoutMs);
+                deps.log(`new session ${sessionId}`);
+            })().finally(() => {
+                reopening = null;
+            });
+        }
+        return reopening;
+    }
+    async function send(line, message) {
+        const isInitialize = message?.method === "initialize";
+        const replaySafe = isReplaySafe(message);
+        let tokenRefreshed = false;
+        let sessionReopened = false;
+        for (let attempt = 0;; attempt++) {
+            const canRetry = attempt < retryDelaysMs.length && !isInitialize;
+            if (reopening)
+                await reopening.catch(() => { });
+            let response;
+            try {
+                response = await post(line, isInitialize ? null : sessionId, isInitialize ? initializeTimeoutMs : requestTimeoutMs);
+            }
+            catch (err) {
+                // Network error or timeout: the environment may be restarting, and the session is suspect.
+                const text = err instanceof Error ? err.message : String(err);
+                deps.log(`${message?.method ?? "request"} failed: ${text}`);
+                if (!canRetry)
+                    throw err;
+                await deps.sleep(retryDelaysMs[attempt]);
+                try {
+                    await reopenSession();
+                    sessionReopened = true;
+                }
+                catch (e) {
+                    deps.log(`reopen failed: ${e instanceof Error ? e.message : String(e)}`);
+                }
+                if (!replaySafe) {
+                    throw new Error(`${text}. The connection to D365 was lost (restart or deploy?); ` +
+                        `${sessionReopened ? "a new session is open" : "reconnecting"}. This call may or may not have run: check before retrying it.`);
+                }
+                continue;
+            }
+            if (response.status === 401 && !tokenRefreshed) {
+                deps.log("401: refreshing the token and retrying");
+                tokenRefreshed = true;
+                await deps.getToken(true);
+                continue;
+            }
+            if (response.status === 401)
+                throw new Error("authentication failed (401) after refreshing the token");
+            if (!isInitialize && sessionId && isSessionLost(response) && !sessionReopened) {
+                // The server rejected the call without running it: safe to replay on a new session.
+                deps.log(`session ${sessionId} lost (HTTP ${response.status})`);
+                try {
+                    await reopenSession();
+                    sessionReopened = true;
+                    continue;
+                }
+                catch (e) {
+                    deps.log(`reopen failed: ${e instanceof Error ? e.message : String(e)}`);
+                    if (!canRetry)
+                        throw e;
+                    await deps.sleep(retryDelaysMs[attempt]);
+                    continue;
+                }
+            }
+            if (TRANSIENT_STATUS.has(response.status)) {
+                deps.log(`HTTP ${response.status}${canRetry ? `, retrying in ${retryDelaysMs[attempt] / 1000} s` : ""}`);
+                if (!canRetry)
+                    throw new Error(`HTTP ${response.status} from D365 after ${attempt + 1} attempts`);
+                await deps.sleep(retryDelaysMs[attempt]);
+                continue;
+            }
+            if (isInitialize || response.sessionId)
+                sessionId = response.sessionId || sessionId;
+            return response;
+        }
+    }
+    function writeError(id, text) {
+        deps.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `d365-erp-mcp: ${text}` } }));
+    }
+    /** Handles one line from the client; resolves once its answer (if any) is written. */
+    async function handle(line) {
+        let message = null;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            // forwarded as-is
+        }
+        const id = message && message.id !== undefined && message.id !== null ? message.id : null;
+        if (message?.method === "initialize") {
+            initializeLine = line;
+            sessionId = null;
+        }
+        if (message?.method === "notifications/initialized")
+            initializedLine = line;
+        try {
+            const response = await send(line, message);
+            const messages = parseMessages(response.body);
+            for (const m of messages)
+                deps.write(JSON.stringify(m));
+            if (id !== null && messages.length === 0) {
+                writeError(id, `HTTP ${response.status} without a JSON-RPC response: ${(response.body || "").slice(0, 200)}`);
+            }
+        }
+        catch (err) {
+            const text = err instanceof Error ? err.message : String(err);
+            deps.log(`error: ${text}`);
+            if (id !== null)
+                writeError(id, text);
+        }
+    }
+    return { handle };
+}
+/** Reads the bridge settings from the environment variables SETUP.md documents. */
+export function configFromEnv(env) {
+    const missing = ["D365_URL", "D365_TENANT_ID", "D365_CLIENT_ID", "D365_CLIENT_SECRET"].filter((k) => !env[k]?.trim());
+    if (missing.length > 0) {
+        throw new Error(`trxa mcp-bridge: set ${missing.join(", ")} in the MCP server's "env" settings (see SETUP.md).`);
+    }
+    let url;
+    try {
+        url = new URL(env.D365_URL.trim());
+    }
+    catch {
+        throw new Error(`trxa mcp-bridge: D365_URL is not a URL: ${env.D365_URL}`);
+    }
+    if (url.protocol !== "https:")
+        throw new Error("trxa mcp-bridge: D365_URL must start with https://");
+    return {
+        // Accept the address as copied from the browser: drop any path, query or trailing /mcp.
+        environmentUrl: `${url.protocol}//${url.host}`,
+        tenantId: env.D365_TENANT_ID.trim(),
+        clientId: env.D365_CLIENT_ID.trim(),
+        clientSecret: env.D365_CLIENT_SECRET.trim(),
+        requestTimeoutMs: Number(env.D365_MCP_TIMEOUT_MS) || 90000,
+    };
+}
+function httpsPost(mcpUrl, body, sessionId, token, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json, text/event-stream",
+            "Content-Length": Buffer.byteLength(body),
+        };
+        if (sessionId)
+            headers["Mcp-Session-Id"] = sessionId;
+        const req = https.request(
+        // A new connection per request: no stale pooled sockets after a restart.
+        { hostname: mcpUrl.hostname, path: mcpUrl.pathname, method: "POST", headers, agent: false }, (res) => {
+            const next = res.headers["mcp-session-id"];
+            let data = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => (data += chunk));
+            res.on("end", () => resolve({ body: data, sessionId: (Array.isArray(next) ? next[0] : next) || sessionId, status: res.statusCode ?? 0 }));
+            res.on("error", reject);
+        });
+        req.setTimeout(timeoutMs, () => req.destroy(new Error(`no response within ${timeoutMs / 1000} s`)));
+        req.on("error", reject);
+        req.write(body);
+        req.end();
+    });
+}
+/** `trxa mcp-bridge`: runs until stdin closes. */
+export async function runMcpBridge(env = process.env) {
+    const config = configFromEnv(env);
+    const { ConfidentialClientApplication } = await import("@azure/msal-node");
+    const msal = new ConfidentialClientApplication({
+        auth: { clientId: config.clientId, authority: `https://login.microsoftonline.com/${config.tenantId}`, clientSecret: config.clientSecret },
+    });
+    const scopes = [`${config.environmentUrl}/.default`];
+    const mcpUrl = new URL(`${config.environmentUrl}/mcp`);
+    let token = null;
+    let expires = 0;
+    const log = (text) => process.stderr.write(`[trxa mcp-bridge ${new Date().toISOString()}] ${text}\n`);
+    const deps = {
+        async getToken(forceRefresh) {
+            if (!forceRefresh && token && Date.now() < expires - 60000)
+                return token;
+            const result = await msal.acquireTokenByClientCredential({ scopes, skipCache: forceRefresh });
+            if (!result?.accessToken)
+                throw new Error("Microsoft Entra ID returned no access token");
+            token = result.accessToken;
+            expires = result.expiresOn ? result.expiresOn.getTime() : Date.now() + 300000;
+            return token;
+        },
+        post: (body, sessionId, accessToken, timeoutMs) => httpsPost(mcpUrl, body, sessionId, accessToken, timeoutMs),
+        write: (line) => process.stdout.write(line + "\n"),
+        log,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    };
+    const bridge = createBridge(deps, { requestTimeoutMs: config.requestTimeoutMs });
+    log(`forwarding to ${mcpUrl.href}`);
+    // Warm the token without blocking startup: the client's connect timeout is short.
+    deps.getToken(false).then(() => log("signed in to Microsoft Entra ID"), (err) => log(`not signed in yet: ${err instanceof Error ? err.message : String(err)}`));
+    const rl = readline.createInterface({ input: process.stdin });
+    rl.on("line", (line) => {
+        if (line.trim())
+            void bridge.handle(line);
+    });
+    await new Promise((resolve) => rl.on("close", () => resolve()));
+}

package/dist/normalize.d.ts

@@ -0,0 +1,21 @@
+import type { Recording, RecordingNode } from "./schema.js";
+/** A leaf action node from Recording.xml, flattened into execution order. */
+export interface TestStep {
+    sequence: number;
+    description: string;
+    /** Resolved via the leaf's FormId against Recording.FormContexts. Null for MenuItemUserAction,
+     *  which navigates *to* a form rather than acting within one already-known context. */
+    formName: string | null;
+    formId: string | null;
+    node: RecordingNode;
+}
+/** The mechanics of a replay: an ordered list of steps, nothing about pass/fail. QA vocabulary
+ *  calls this a Test Script -- the executable realization of a recording's steps. */
+export interface TestScript {
+    name: string;
+    canonicalId: string;
+    description: string;
+    steps: TestStep[];
+}
+/** Flattens a parsed Recording into an ordered list of executable steps. */
+export declare function normalizeRecording(recording: Recording): TestScript;

package/dist/normalize.js

@@ -0,0 +1,43 @@
+function formIdOf(node) {
+    if (node.kind === "CommandUserAction" || node.kind === "PropertyUserAction") {
+        return node.FormId;
+    }
+    if (node.kind === "Unknown") {
+        const raw = node.raw.FormId;
+        return typeof raw === "string" ? raw : null;
+    }
+    return null;
+}
+/** Depth-first walk collecting every non-Scope (i.e. actionable) node, in document order. */
+function collectLeaves(node, out) {
+    if (node.kind === "Scope") {
+        for (const child of node.Children)
+            collectLeaves(child, out);
+    }
+    else {
+        out.push(node);
+    }
+}
+/** Flattens a parsed Recording into an ordered list of executable steps. */
+export function normalizeRecording(recording) {
+    const leaves = [];
+    collectLeaves(recording.RootScope, leaves);
+    const steps = leaves
+        .map((node) => {
+        const formId = formIdOf(node);
+        return {
+            sequence: node.Sequence,
+            description: node.Description,
+            formId,
+            formName: formId ? recording.FormContexts[formId]?.FormName ?? null : null,
+            node,
+        };
+    })
+        .sort((a, b) => a.sequence - b.sequence);
+    return {
+        name: recording.Name,
+        canonicalId: recording.CanonicalId,
+        description: recording.Description,
+        steps,
+    };
+}

package/dist/parse.d.ts

@@ -0,0 +1,3 @@
+import type { Recording } from "./schema.js";
+/** Parses a `Recording.xml` document into a typed Recording tree. */
+export declare function parseRecordingXml(xml: string): Recording;

package/dist/parse.js

@@ -0,0 +1,233 @@
+import { XMLParser } from "fast-xml-parser";
+/**
+ * Tags that must always parse to an array, even when exactly one occurs in the XML -- fast-xml-
+ * parser otherwise collapses a single child into a bare object, and every downstream `.map()`
+ * over these (`collectLeaves`, `parseCommandArgument`, `parseFormContexts`) would throw on a
+ * recording with only one child/argument. Adding a new element type that can repeat (Scope
+ * children, command arguments, etc.) means adding its tag name here too -- there's no other
+ * signal that forces array mode.
+ * `KeyValueOfstringFormContextyaScvdpM` is the mangled tag fast-xml-parser sees for a WCF
+ * `Dictionary<string, FormContext>` entry (`DataContractSerializer`'s generic-type name-mangling
+ * convention) -- not verified against other D365FO versions, but it's the .NET serializer's own
+ * naming scheme, not something specific to one recording, so unlikely to change independently.
+ */
+const ARRAY_TAGS = new Set([
+    "Node",
+    "Annotation",
+    "CommandArgument",
+    "string",
+    "KeyValueOfstringFormContextyaScvdpM",
+]);
+function makeParser() {
+    return new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        removeNSPrefix: true,
+        parseTagValue: false,
+        parseAttributeValue: false,
+        trimValues: true,
+        isArray: (tagName) => ARRAY_TAGS.has(tagName),
+    });
+}
+/** True when the parsed element is `{ "@_nil": "true" }` (xsi:nil marker) or otherwise empty. */
+function isNil(v) {
+    if (v === undefined || v === null)
+        return true;
+    if (typeof v === "object" && !Array.isArray(v)) {
+        const o = v;
+        return o["@_nil"] === "true";
+    }
+    return false;
+}
+/** Reads a simple text-content element, honoring xsi:nil. Preserves strings verbatim (no numeric coercion). */
+function text(v) {
+    if (isNil(v))
+        return null;
+    if (typeof v === "string")
+        return v;
+    return null;
+}
+function textReq(v, field) {
+    const t = text(v);
+    if (t === null)
+        throw new Error(`Expected required text field "${field}" to be present`);
+    return t;
+}
+function num(v) {
+    const t = text(v);
+    if (t === null || t === "")
+        return null;
+    const n = Number(t);
+    return Number.isNaN(n) ? null : n;
+}
+function numReq(v, field) {
+    const n = num(v);
+    if (n === null)
+        throw new Error(`Expected required numeric field "${field}" to be present`);
+    return n;
+}
+function bool(v) {
+    return text(v) === "true";
+}
+/** Unwraps a collection element that is either nil, a single child, or an array of children. */
+function collection(v, childTag) {
+    if (isNil(v))
+        return [];
+    if (typeof v === "string")
+        return []; // self-closed with no attrs -> parsed as ""
+    const obj = v;
+    const child = obj[childTag];
+    if (child === undefined)
+        return [];
+    return Array.isArray(child) ? child : [child];
+}
+function parseCommandArgument(raw) {
+    return {
+        IsReference: bool(raw.IsReference),
+        Value: textReq(raw.Value, "CommandArgument.Value"),
+    };
+}
+function parseFormContext(raw) {
+    return {
+        FormID: textReq(raw.FormID, "FormContext.FormID"),
+        FormName: textReq(raw.FormName, "FormContext.FormName"),
+        RecordingName: textReq(raw.RecordingName, "FormContext.RecordingName"),
+        HasMetadata: bool(raw.HasMetadata),
+        Sequence: numReq(raw.Sequence, "FormContext.Sequence"),
+        Annotations: raw.Annotations,
+    };
+}
+function parseFormContexts(raw) {
+    const entries = collection(raw, "KeyValueOfstringFormContextyaScvdpM");
+    const result = {};
+    for (const entry of entries) {
+        const key = textReq(entry.Key, "FormContexts.Key");
+        result[key] = parseFormContext(entry.Value);
+    }
+    return result;
+}
+function nodeBaseFields(raw) {
+    return {
+        Id: textReq(raw.Id, "Node.Id"),
+        Description: text(raw.Description) ?? "",
+        CustomDescription: text(raw.CustomDescription),
+        ParentSequence: numReq(raw.ParentSequence, "Node.ParentSequence"),
+        Sequence: numReq(raw.Sequence, "Node.Sequence"),
+        ScreenshotUri: text(raw.ScreenshotUri),
+    };
+}
+function userActionBaseFields(raw) {
+    return {
+        ...nodeBaseFields(raw),
+        GlobalId: textReq(raw.GlobalId, "UserAction.GlobalId"),
+        SystemGenerated: bool(raw.SystemGenerated),
+    };
+}
+function parseScope(raw) {
+    return {
+        kind: "Scope",
+        ...nodeBaseFields(raw),
+        Name: text(raw.Name) ?? "",
+        IsForm: bool(raw.IsForm),
+        IsStepGroup: bool(raw.IsStepGroup),
+        ScopeType: text(raw.ScopeType) ?? "",
+        Children: collection(raw.Children, "Node").map((n) => parseNode(n)),
+    };
+}
+function parseMenuItemUserAction(raw) {
+    return {
+        kind: "MenuItemUserAction",
+        ...userActionBaseFields(raw),
+        MenuItemName: textReq(raw.MenuItemName, "MenuItemUserAction.MenuItemName"),
+        MenuItemType: text(raw.MenuItemType) ?? "",
+        NavigationPath: collection(raw.NavigationPath, "string").map((s) => textReq(s, "NavigationPath.string")),
+    };
+}
+function parseCommandUserAction(raw) {
+    return {
+        kind: "CommandUserAction",
+        ...userActionBaseFields(raw),
+        FormId: textReq(raw.FormId, "CommandUserAction.FormId"),
+        ControlName: text(raw.ControlName) ?? "",
+        ControlType: text(raw.ControlType) ?? "",
+        ControlLabel: text(raw.ControlLabel) ?? "",
+        ControlLabelId: text(raw.ControlLabelId) ?? "",
+        CommandName: textReq(raw.CommandName, "CommandUserAction.CommandName"),
+        Arguments: collection(raw.Arguments, "CommandArgument").map((a) => parseCommandArgument(a)),
+        ListContext: text(raw.ListContext),
+        RowIndex: num(raw.RowIndex),
+        ReturnType: text(raw.ReturnType) ?? "",
+        ReturnValue: text(raw.ReturnValue),
+        TaskId: text(raw.TaskId),
+    };
+}
+function parsePropertyUserAction(raw) {
+    return {
+        kind: "PropertyUserAction",
+        ...userActionBaseFields(raw),
+        FormId: textReq(raw.FormId, "PropertyUserAction.FormId"),
+        ControlName: text(raw.ControlName) ?? "",
+        ControlType: text(raw.ControlType) ?? "",
+        ControlLabel: text(raw.ControlLabel) ?? "",
+        ControlLabelId: text(raw.ControlLabelId) ?? "",
+        BoundDataSource: text(raw.BoundDataSource) ?? "",
+        BoundProperty: text(raw.BoundProperty) ?? "",
+        PropertyName: text(raw.PropertyName) ?? "",
+        UserActionType: text(raw.UserActionType) ?? "",
+        Value: text(raw.Value) ?? "",
+        ValueLabel: text(raw.ValueLabel),
+        IsReference: bool(raw.IsReference),
+        ListContext: text(raw.ListContext),
+        RowIndex: num(raw.RowIndex),
+    };
+}
+function parseUnknownUserAction(raw, xsiType) {
+    return {
+        kind: "Unknown",
+        ...userActionBaseFields(raw),
+        xsiType,
+        raw,
+    };
+}
+function parseNode(raw) {
+    const xsiType = raw["@_type"] ?? "Scope";
+    switch (xsiType) {
+        case "Scope":
+            return parseScope(raw);
+        case "MenuItemUserAction":
+            return parseMenuItemUserAction(raw);
+        case "CommandUserAction":
+            return parseCommandUserAction(raw);
+        case "PropertyUserAction":
+            return parsePropertyUserAction(raw);
+        default:
+            return parseUnknownUserAction(raw, xsiType);
+    }
+}
+/** Parses a `Recording.xml` document into a typed Recording tree. */
+export function parseRecordingXml(xml) {
+    const parser = makeParser();
+    const doc = parser.parse(xml);
+    const root = doc.Recording;
+    if (!root) {
+        throw new Error("Document does not contain a root <Recording> element");
+    }
+    const rootScopeRaw = root.RootScope;
+    const rootScope = {
+        kind: "Scope",
+        ...nodeBaseFields(rootScopeRaw),
+        Name: text(root.Name) ?? "",
+        IsForm: false,
+        IsStepGroup: false,
+        ScopeType: "Root",
+        Children: collection(rootScopeRaw.Children, "Node").map((n) => parseNode(n)),
+    };
+    return {
+        CanonicalId: textReq(root.CanonicalId, "Recording.CanonicalId"),
+        CurrentSequence: numReq(root.CurrentSequence, "Recording.CurrentSequence"),
+        Description: text(root.Description) ?? "",
+        Name: textReq(root.Name, "Recording.Name"),
+        FormContexts: parseFormContexts(root.FormContexts),
+        RootScope: rootScope,
+    };
+}

package/dist/plan-runner.d.ts

@@ -0,0 +1,27 @@
+import type { PlanRun } from "./planrun-schema.js";
+import { type TestRun } from "./report-schema.js";
+export type SuiteRunStatus = "missing" | "incomplete" | "passed" | "failed";
+export interface SuiteRunSummary {
+    suiteId: string;
+    /** Snapshotted from `PlanRun.suiteNames`; falls back to `suiteId` for a PlanRun persisted before
+     *  that field existed. */
+    suiteName: string;
+    status: SuiteRunStatus;
+    testRun: TestRun | null;
+}
+export type PlanOverallStatus = "all-passed" | "has-failures" | "incomplete" | "missing-runs";
+export interface PlanStatus {
+    planId: string;
+    runId: string;
+    suites: SuiteRunSummary[];
+    overall: PlanOverallStatus;
+}
+/**
+ * Pure aggregation, no filesystem access: given a PlanRun and the TestRun already loaded for each
+ * of its snapshotted suites (or null if that suite's run file doesn't exist for this runId),
+ * computes a rollup. Deliberately reads `run.suiteIds` -- the suite list as it existed when the
+ * run started -- rather than the live TestPlan's `suites`, so a run's status can't retroactively
+ * change just because the plan later gained or lost a suite (confirmed live: adding a suite to
+ * Accounts Payable flipped an already-passed run to "Missing runs" before this fix).
+ */
+export declare function aggregatePlanStatus(run: PlanRun, testRuns: Map<string, TestRun | null>): PlanStatus;

package/dist/plan-runner.js

@@ -0,0 +1,36 @@
+import { TERMINAL_STATUSES } from "./report-schema.js";
+function summarizeSuiteRun(suiteId, suiteName, testRun) {
+    if (!testRun)
+        return { suiteId, suiteName, status: "missing", testRun: null };
+    const statuses = Object.values(testRun.results).map((r) => r.status);
+    const allTerminal = statuses.every((s) => TERMINAL_STATUSES.has(s));
+    if (!allTerminal)
+        return { suiteId, suiteName, status: "incomplete", testRun };
+    const hasFailure = statuses.some((s) => s === "failed" || s === "blocked");
+    return { suiteId, suiteName, status: hasFailure ? "failed" : "passed", testRun };
+}
+/**
+ * Pure aggregation, no filesystem access: given a PlanRun and the TestRun already loaded for each
+ * of its snapshotted suites (or null if that suite's run file doesn't exist for this runId),
+ * computes a rollup. Deliberately reads `run.suiteIds` -- the suite list as it existed when the
+ * run started -- rather than the live TestPlan's `suites`, so a run's status can't retroactively
+ * change just because the plan later gained or lost a suite (confirmed live: adding a suite to
+ * Accounts Payable flipped an already-passed run to "Missing runs" before this fix).
+ */
+export function aggregatePlanStatus(run, testRuns) {
+    const suites = run.suiteIds.map((suiteId) => summarizeSuiteRun(suiteId, run.suiteNames[suiteId] ?? suiteId, testRuns.get(suiteId) ?? null));
+    let overall;
+    if (suites.some((s) => s.status === "failed")) {
+        overall = "has-failures";
+    }
+    else if (suites.some((s) => s.status === "incomplete")) {
+        overall = "incomplete";
+    }
+    else if (suites.some((s) => s.status === "missing")) {
+        overall = "missing-runs";
+    }
+    else {
+        overall = "all-passed";
+    }
+    return { planId: run.planId, runId: run.id, suites, overall };
+}