trxa-tool 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,850 @@
+#!/usr/bin/env node
+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";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { loadTestScript, buildTestScript } from "./build-test-script.js";
+import { analyzeLibrary } from "./analyze.js";
+import { toCsv } from "./csv.js";
+import { suggestInputs } from "./suggest-inputs.js";
+import { validateTestCase } from "./testcase-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";
+import { initTestRun, readTestRun, recordResult } from "./report.js";
+import { initPlanRun, readPlanRun } from "./planrun.js";
+import { aggregatePlanStatus } from "./plan-runner.js";
+import { exportLibrary, importLibrary } from "./library-archive.js";
+import { TERMINAL_STATUSES } from "./report-schema.js";
+import { defaultClaudeProjectsRoot, findLatestTranscript, measureTokens } from "./token-usage.js";
+export { loadTestScript, buildTestScript };
+/**
+ * Assumes the compiled entry file (this file, once built) sits exactly one directory below the
+ * repo root -- true for `dist/index.js` per `tsconfig.json`'s `outDir`, but silent if that layout
+ * ever changes (e.g. a nested `dist/src/index.js`): `studio start`/`stop` and the version lookup
+ * would then resolve the wrong directory with no error, since `path.resolve` doesn't validate
+ * what it points at. Computed once here (was previously duplicated in `cmdStudio` and `main`).
+ */
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] ?? null : null;
+}
+/** Reads a JSON-valued flag that accepts either an inline string (e.g. `--outputs '{"a":"b"}'`) or
+ *  a file path (`--outputs-file path/to.json`). The file form exists to sidestep shell-specific
+ *  argv-quoting bugs, not just as a convenience for long payloads: Windows PowerShell 5.1's
+ *  argument-passing layer to a native executable (node.exe isn't a cmdlet) can silently corrupt
+ *  inline JSON containing quote characters and/or spaces before Node ever sees `process.argv` --
+ *  see POWERSHELL-JSON-ARGS.md for two distinct reproduced failure modes and why a `--%`-plus-
+ *  escaping workaround was needed before this flag existed. Throws if both forms are passed rather
+ *  than silently preferring one, since that's more likely a caller mistake than an intentional
+ *  choice. */
+async function jsonFlagValue(rest, inlineFlag, fileFlag) {
+    const inline = flagValue(rest, inlineFlag);
+    const filePath = flagValue(rest, fileFlag);
+    if (inline !== null && filePath !== null) {
+        throw new Error(`Pass either ${inlineFlag} or ${fileFlag}, not both`);
+    }
+    if (filePath !== null)
+        return JSON.parse(await readFile(filePath, "utf-8"));
+    if (inline !== null)
+        return JSON.parse(inline);
+    return undefined;
+}
+async function outputJson(value, outPath, successMessage) {
+    const json = JSON.stringify(value, null, 2);
+    if (outPath) {
+        await writeFile(outPath, json, "utf-8");
+        console.error(successMessage);
+    }
+    else {
+        console.log(json);
+    }
+}
+async function loadTestCaseFile(testcasesDir, testCaseId) {
+    const filePath = path.join(testcasesDir, `${testCaseId}.json`);
+    const raw = JSON.parse(await readFile(filePath, "utf-8"));
+    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 `[]`. 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) {
+    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 folder.fixtures.map((f) => f.fixture);
+}
+async function loadSuite(suitePath) {
+    const raw = JSON.parse(await readFile(suitePath, "utf-8"));
+    return validateTestSuite(raw);
+}
+async function loadPlan(planPath) {
+    const raw = JSON.parse(await readFile(planPath, "utf-8"));
+    return validateTestPlan(raw);
+}
+// --- Commands ---
+async function cmdParse(args) {
+    const [inputPath, ...rest] = args;
+    if (!inputPath) {
+        throw new Error("Usage: trxa parse <file.axtr> [-o out.testscript.json]");
+    }
+    const outPath = flagValue(rest, "-o");
+    const testScript = await buildTestScript(inputPath);
+    await outputJson(testScript, outPath, `Wrote ${testScript.steps.length} steps to ${outPath}`);
+}
+async function cmdSuggestInputs(args) {
+    const [inputPath, ...rest] = args;
+    if (!inputPath) {
+        throw new Error("Usage: trxa suggest-inputs <file.axtr> [-o draft.json]");
+    }
+    const outPath = flagValue(rest, "-o");
+    const script = await loadTestScript(inputPath);
+    const draft = suggestInputs(script);
+    await outputJson(draft, outPath, `Wrote ${draft.candidates.length} candidate inputs to ${outPath}`);
+}
+async function cmdValidateTestCase(args) {
+    const [filePath] = args;
+    if (!filePath)
+        throw new Error("Usage: trxa validate-testcase <testcase.json>");
+    const raw = JSON.parse(await readFile(filePath, "utf-8"));
+    const testCase = validateTestCase(raw);
+    console.error(`OK: "${testCase.id}" is a valid test case (${testCase.inputs.length} inputs, ${testCase.expectations.length} expectations)`);
+}
+async function cmdValidateFixture(args) {
+    const [filePath] = args;
+    if (!filePath)
+        throw new Error("Usage: trxa validate-fixture <fixture.json>");
+    const raw = JSON.parse(await readFile(filePath, "utf-8"));
+    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;
+    if (!filePath)
+        throw new Error("Usage: trxa validate-suite <suite.json>");
+    const suite = await loadSuite(filePath);
+    const order = topologicalOrder(suite); // also catches cycles/unknown dependsOn ids
+    console.error(`OK: "${suite.id}" is a valid suite (${order.length} entries, execution order: ${order.join(" -> ")})`);
+}
+async function cmdPlanSuite(args) {
+    const [suitePath] = args;
+    if (!suitePath)
+        throw new Error("Usage: trxa plan-suite <suite.json>");
+    const suite = await loadSuite(suitePath);
+    const order = topologicalOrder(suite);
+    console.log(JSON.stringify({ suiteId: suite.id, executionOrder: order }, null, 2));
+}
+/** Relative to `REPO_ROOT` (where the bundled copy ships from -- see package.json's `files`). The
+ *  canonical source lives under the Claude Code path since that's this repo's own dev-time
+ *  convention too -- both agent tools' SKILL.md format (frontmatter `name`/`description`) is
+ *  identical, only the containing directory each tool scans differs, so one source file gets
+ *  copied verbatim to every target below rather than maintained twice. */
+const SKILL_SOURCE_RELATIVE_PATH = path.join(".claude", "skills", "replay-trxa-testplan", "SKILL.md");
+/** Every location an agent tool discovers a project-scoped skill from, not from anywhere inside an
+ *  installed npm package's own `node_modules` -- so shipping the file in the package alone doesn't
+ *  make any of these tools find it. This command bridges that gap explicitly, same "customer says
+ *  where, nothing writes outside their project on its own" philosophy as Studio's working-folder
+ *  setting. Add an entry here, not a new command, if another tool's convention needs supporting. */
+const SKILL_INSTALL_TARGETS = [
+    { tool: "Claude Code", relativePath: path.join(".claude", "skills", "replay-trxa-testplan", "SKILL.md") },
+    { tool: "Codex", relativePath: path.join(".agents", "skills", "replay-trxa-testplan", "SKILL.md") },
+];
+async function cmdInitSkill(args) {
+    const force = args.includes("--force");
+    const sourcePath = path.join(REPO_ROOT, SKILL_SOURCE_RELATIVE_PATH);
+    if (!existsSync(sourcePath)) {
+        throw new Error(`Bundled skill file not found at ${sourcePath} -- this install may be missing it.`);
+    }
+    const alreadyExisting = SKILL_INSTALL_TARGETS.filter((t) => existsSync(path.join(process.cwd(), t.relativePath)));
+    if (alreadyExisting.length > 0 && !force) {
+        throw new Error(`Refusing to overwrite existing file(s): ${alreadyExisting.map((t) => t.relativePath).join(", ")} ` +
+            `(pass --force to overwrite)`);
+    }
+    const content = await readFile(sourcePath, "utf-8");
+    for (const target of SKILL_INSTALL_TARGETS) {
+        const destPath = path.join(process.cwd(), target.relativePath);
+        await mkdir(path.dirname(destPath), { recursive: true });
+        await writeFile(destPath, content, "utf-8");
+    }
+    console.error(`Installed the replay-trxa-testplan skill for ${SKILL_INSTALL_TARGETS.map((t) => t.tool).join(" and ")} ` +
+        `(${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 [--name "<run name>"]');
+    }
+    const suite = await loadSuite(suitePath);
+    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/ [--name "<run name>"]');
+    }
+    const plan = await loadPlan(planPath);
+    const planDir = path.dirname(planPath);
+    const suites = await Promise.all(plan.suites.map(async (entry) => {
+        const suite = await loadSuite(path.resolve(planDir, entry.suitePath));
+        return { id: suite.id, name: suite.name };
+    }));
+    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));
+}
+async function cmdResolveNext(args) {
+    const [suitePath, testRunPath, ...rest] = args;
+    const testcasesDir = flagValue(rest, "--testcases-dir");
+    const fixturesDir = flagValue(rest, "--fixtures-dir");
+    if (!suitePath || !testRunPath || !testcasesDir) {
+        throw new Error("Usage: trxa resolve-next <suite.json> <testrun.json> --testcases-dir <dir> [--fixtures-dir <dir>]");
+    }
+    const suite = await loadSuite(suitePath);
+    const testRun = await readTestRun(testRunPath);
+    const progress = nextStep(suite, testRun);
+    if (progress.status === "newly-blocked") {
+        for (const id of progress.blockedIds) {
+            await recordResult(testRunPath, id, { status: "blocked" });
+        }
+        console.log(JSON.stringify({ status: "blocked", blockedIds: progress.blockedIds }, null, 2));
+        return;
+    }
+    if (progress.status === "newly-skipped") {
+        for (const id of progress.skippedIds) {
+            await recordResult(testRunPath, id, { status: "skipped" });
+        }
+        console.log(JSON.stringify({ status: "skipped", skippedIds: progress.skippedIds }, null, 2));
+        return;
+    }
+    if (progress.status === "waiting" || progress.status === "complete") {
+        console.log(JSON.stringify({ status: progress.status }, null, 2));
+        return;
+    }
+    // Two passes, deliberately not one: resolving a batch of two or more entries can partially fail
+    // (e.g. one entry's inputBindings are incomplete, confirmed live with a 3-way branch during
+    // development) -- if resolution and the "running" transition were interleaved in a single loop,
+    // an entry resolved earlier in the batch would already be persisted as "running" by the time a
+    // later one throws, leaving the TestRun file half-committed with no way to recover that entry
+    // (it's no longer "pending", so a retried resolve-next won't offer it again, but it never reached
+    // a terminal status either). Resolving every entry first, with no side effects, and only starting
+    // to write "running" transitions once the whole batch has resolved cleanly, keeps the single-entry
+    // case's original atomicity guarantee (a throw here means nothing gets persisted) intact even when
+    // `progress.testCaseIds` has more than one id in it.
+    const resolved = progress.testCaseIds.map((testCaseId) => {
+        const entry = suite.entries.find((e) => e.testCaseId === testCaseId);
+        return { testCaseId, entry };
+    });
+    const fixtures = fixturesDir ? await loadFixtures(fixturesDir) : [];
+    const toRun = await Promise.all(resolved.map(async ({ testCaseId, entry }) => {
+        const testCase = await loadTestCaseFile(testcasesDir, testCaseId);
+        const resolvedInputs = resolveInputs(entry, testCase, testRun, fixtures);
+        // `resolveInputs` deliberately leaves "autogenerated" params unresolved -- surface them here
+        // (with the param's own description/example as generation guidance) rather than in the pure
+        // resolver, since inventing a value is the orchestrating LLM's job, not this CLI's.
+        const autogeneratedParams = testCase.inputs
+            .filter((p) => entry.inputBindings[p.name]?.kind === "autogenerated")
+            .map((p) => ({ name: p.name, description: p.description, example: p.example }));
+        return { testCaseId, entry, testCase, resolvedInputs, autogeneratedParams };
+    }));
+    // Sequential, not Promise.all -- each recordResult call does its own read-modify-write of the
+    // same testRunPath file, so writing them concurrently would risk one overwriting another's
+    // "running" transition. By this point every entry has already resolved successfully, so this
+    // loop itself can't fail partway through for a data reason -- only a filesystem-level failure
+    // could leave it partially applied, the same exposure `record-result` already has today.
+    const runnable = [];
+    for (const { testCaseId, entry, testCase, resolvedInputs, autogeneratedParams } of toRun) {
+        await recordResult(testRunPath, testCaseId, { status: "running", inputs: resolvedInputs });
+        runnable.push({
+            testCaseId,
+            testScriptPath: testCase.testScriptPath,
+            legalEntity: entry.legalEntity,
+            resolvedInputs,
+            autogeneratedParams,
+            outputs: testCase.outputs,
+            expectations: testCase.expectations,
+        });
+    }
+    console.log(JSON.stringify({ status: "runnable", runnable }, null, 2));
+}
+async function cmdRecordResult(args) {
+    const [testRunPath, testCaseId, ...rest] = args;
+    const status = flagValue(rest, "--status");
+    const tokensRaw = flagValue(rest, "--tokens");
+    const costRaw = flagValue(rest, "--cost");
+    if (!testRunPath || !testCaseId || !status) {
+        throw new Error('Usage: trxa record-result <testrun.json> <testCaseId> --status passed|failed|blocked ' +
+            '(--outputs \'{"name":"value"}\' | --outputs-file <path>) ' +
+            "[--assertions '[{\"description\":\"...\",\"passed\":true,\"actual\":\"...\"}]' | --assertions-file <path>] " +
+            '[--inputs \'{"name":"value"}\' | --inputs-file <path>] ' +
+            "[--tokens <number>] (auto-measured from Claude Code's session log if omitted) [--cost <usd>] " +
+            "[--messages '[\"...\"]' | --messages-file <path>]. " +
+            "The *-file flags read JSON from a file instead of argv -- prefer them on Windows PowerShell, whose " +
+            "argument-passing layer can corrupt inline JSON containing quotes/spaces (see MANUAL.md, Windows PowerShell section).");
+    }
+    const outputs = await jsonFlagValue(rest, "--outputs", "--outputs-file");
+    const assertionResults = await jsonFlagValue(rest, "--assertions", "--assertions-file");
+    const inputs = await jsonFlagValue(rest, "--inputs", "--inputs-file");
+    const costUsd = costRaw ? Number(costRaw) : undefined;
+    const messages = await jsonFlagValue(rest, "--messages", "--messages-file");
+    // Auto-measure real token usage from Claude Code's own session log when the caller didn't pass
+    // an explicit number and this result is reaching a terminal status with a known start time --
+    // no separate step for the orchestrating LLM to remember. An explicit --tokens still wins (e.g.
+    // a future execution mode with a better source), and this is skipped silently -- not an error --
+    // if no transcript can be found (see findLatestTranscript's own caveat about concurrent sessions).
+    let tokensUsed = tokensRaw ? Number(tokensRaw) : undefined;
+    if (tokensUsed === undefined && TERMINAL_STATUSES.has(status)) {
+        const existingRun = await readTestRun(testRunPath);
+        const startedAt = existingRun.results[testCaseId]?.startedAt;
+        if (startedAt) {
+            const transcriptPath = findLatestTranscript(defaultClaudeProjectsRoot());
+            if (transcriptPath) {
+                tokensUsed = measureTokens(transcriptPath, startedAt, new Date().toISOString());
+            }
+        }
+    }
+    const testRun = await recordResult(testRunPath, testCaseId, {
+        status,
+        outputs,
+        assertionResults,
+        inputs,
+        tokensUsed,
+        costUsd,
+        messages,
+    });
+    console.error(`Recorded "${testCaseId}" as ${status} in ${testRunPath}`);
+    console.log(JSON.stringify(testRun.results[testCaseId], null, 2));
+}
+async function cmdMeasureTokens(args) {
+    const since = flagValue(args, "--since");
+    const until = flagValue(args, "--until");
+    const transcriptOverride = flagValue(args, "--transcript");
+    if (!since || !until) {
+        throw new Error("Usage: trxa measure-tokens --since <isoTimestamp> --until <isoTimestamp> [--transcript <path>]");
+    }
+    const transcriptPath = transcriptOverride ?? findLatestTranscript(defaultClaudeProjectsRoot());
+    if (!transcriptPath) {
+        console.log(JSON.stringify({ tokensUsed: null, transcriptPath: null, reason: "no Claude Code session transcript found" }, null, 2));
+        return;
+    }
+    const tokensUsed = measureTokens(transcriptPath, since, until);
+    console.log(JSON.stringify({ tokensUsed, transcriptPath }, null, 2));
+}
+async function cmdValidatePlan(args) {
+    const [planPath] = args;
+    if (!planPath)
+        throw new Error("Usage: trxa validate-plan <plan.json>");
+    const plan = await loadPlan(planPath);
+    const planDir = path.dirname(planPath);
+    for (const entry of plan.suites) {
+        const resolvedSuitePath = path.resolve(planDir, entry.suitePath);
+        const suite = await loadSuite(resolvedSuitePath);
+        if (suite.id !== entry.suiteId) {
+            throw new Error(`Plan "${plan.id}": entry declares suiteId "${entry.suiteId}" but ${entry.suitePath} has id "${suite.id}"`);
+        }
+        topologicalOrder(suite); // catches cycles/unknown dependsOn ids within that suite
+    }
+    console.error(`OK: "${plan.id}" is a valid plan (${plan.suites.length} suites, all resolve and validate)`);
+}
+async function cmdPlanStatus(args) {
+    const [planPath, runPath, ...rest] = args;
+    const testrunsDir = flagValue(rest, "--testruns-dir");
+    if (!planPath || !runPath || !testrunsDir) {
+        throw new Error("Usage: trxa plan-status <plan.json> <run.json> --testruns-dir <dir>");
+    }
+    const plan = await loadPlan(planPath);
+    const run = await readPlanRun(runPath);
+    if (run.planId !== plan.id) {
+        throw new Error(`Plan run at ${runPath} belongs to plan "${run.planId}", not "${plan.id}"`);
+    }
+    const testRuns = new Map();
+    for (const suiteId of run.suiteIds) {
+        const testRunPath = path.join(testrunsDir, `${suiteId}-${run.id}.json`);
+        try {
+            testRuns.set(suiteId, await readTestRun(testRunPath));
+        }
+        catch {
+            testRuns.set(suiteId, null);
+        }
+    }
+    const status = aggregatePlanStatus(run, testRuns);
+    console.log(JSON.stringify({ ...status, startedAt: run.startedAt }, null, 2));
+}
+async function cmdAnalyzeLibrary(args) {
+    const [recordingsDir, ...rest] = args;
+    if (!recordingsDir) {
+        throw new Error("Usage: trxa analyze-library <recordingsDir> [--report analysis/library-report.json] [--csv analysis/scrubbed-values.csv]");
+    }
+    const reportPath = flagValue(rest, "--report") ?? "analysis/library-report.json";
+    const csvPath = flagValue(rest, "--csv") ?? "analysis/scrubbed-values.csv";
+    const { report, scrubbedValues } = await analyzeLibrary(recordingsDir);
+    await mkdir(path.dirname(reportPath), { recursive: true });
+    await mkdir(path.dirname(csvPath), { recursive: true });
+    await writeFile(reportPath, JSON.stringify(report, null, 2), "utf-8");
+    await writeFile(csvPath, toCsv(["recordingFile", "recordingName", "nodeKind", "nodeId", "globalId", "sequence", "fieldPath", "token", "originalValue"], scrubbedValues.map((v) => [
+        v.recordingFile,
+        v.recordingName,
+        v.nodeKind,
+        v.nodeId,
+        v.globalId ?? "",
+        String(v.sequence),
+        v.fieldPath,
+        v.token,
+        v.originalValue,
+    ])), "utf-8");
+    console.error(`Analyzed ${report.recordingsAnalyzed} recording(s) (${report.parseErrors.length} parse error(s)).\n` +
+        `  Structural report (scrubbed, safe to share/review): ${reportPath}\n` +
+        `  Scrubbed-value mapping (CONTAINS REAL BUSINESS DATA -- local only, never share/commit): ${csvPath} (${scrubbedValues.length} value(s))`);
+}
+async function cmdExport(args) {
+    const outPath = flagValue(args, "-o");
+    if (!outPath) {
+        throw new Error("Usage: trxa export -o <backup.zip>");
+    }
+    const result = await exportLibrary(process.cwd(), outPath);
+    console.error(`Exported ${result.fileCount} file(s) from ${result.dirs.join(", ")} to ${result.outPath}`);
+}
+async function cmdImport(args) {
+    const [zipPath, ...rest] = args;
+    const force = rest.includes("--force");
+    if (!zipPath) {
+        throw new Error("Usage: trxa import <backup.zip> [--force]");
+    }
+    const result = await importLibrary(zipPath, process.cwd(), force);
+    if (result.collisions.length > 0) {
+        throw new Error(`Refusing to import: ${result.collisions.length} file(s) already exist and would be overwritten (pass --force to overwrite):\n` +
+            result.collisions.map((c) => `  ${c}`).join("\n"));
+    }
+    console.error(`Imported ${result.fileCount} file(s) from ${zipPath}`);
+}
+const STUDIO_URL = "http://localhost:5173/";
+/** Home-directory-based, not `repoRoot`-relative -- same reasoning as `studio/server/paths.ts`'s
+ *  WORKING_FOLDER (see that file): a real installed package's own directory isn't a stable place
+ *  to keep runtime state like a PID/log file, since it can be wiped on upgrade or need elevated
+ *  permissions to write to. This is state about the *running Studio process*, not project data, so
+ *  it lives next to (not inside) the per-user config `studio/server/settings.ts` also writes to
+ *  `~/.trxa-tool/`. */
+const STUDIO_RUN_DIR = path.join(os.homedir(), ".trxa-tool", "studio-run");
+/** Checks whether `pid` names a currently-running process, without sending a real signal. */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readStudioPid(pidFile) {
+    try {
+        const raw = (await readFile(pidFile, "utf-8")).trim();
+        const pid = Number(raw);
+        return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Polls `url` until it responds (any status) or `timeoutMs` elapses. Returns whether it answered. */
+async function waitForServer(url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            await fetch(url);
+            return true;
+        }
+        catch {
+            // not up yet -- connection refused, still starting
+        }
+        await new Promise((resolve) => setTimeout(resolve, 400));
+    }
+    return false;
+}
+/**
+ * Runs `scriptPath` fully detached from this short-lived CLI process (survives it exiting),
+ * returning the PID of the actual long-running process so `studio stop` can target it later.
+ *
+ * Windows needs a different mechanism than POSIX here. `spawn("cmd", ["/c", scriptPath], {
+ * detached: true, stdio: "inherit" })` looked right -- no error, correct exit code, the script
+ * genuinely ran (confirmed with plain cmd.exe builtins like `echo`) -- but silently dropped
+ * stdout specifically from any nested node.exe process: even bare `npm --version` (no
+ * concurrently/vite/tsx involved) lost its output while still reporting exit code 0. Something
+ * about the CREATE_NEW_PROCESS_GROUP flag Node sets for `detached: true` on Windows breaks stdio
+ * inheritance for node.exe grandchildren specifically. Routing through PowerShell's
+ * `Start-Process -PassThru` instead sidesteps it entirely (confirmed live: full
+ * concurrently/vite/tsx startup output lands in the log correctly, and the returned PID's whole
+ * process tree -- 16 processes deep in testing -- dies cleanly via `taskkill /T /F`).
+ */
+async function launchDetachedScript(scriptPath, cwd) {
+    if (process.platform !== "win32") {
+        const child = spawn("/bin/sh", [scriptPath], { cwd, detached: true, stdio: "ignore" });
+        child.unref();
+        if (!child.pid)
+            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}' ` +
+        `-WorkingDirectory '${cwd}' -WindowStyle Hidden -PassThru; Write-Output $p.Id`;
+    const ps = spawn("powershell", ["-NoProfile", "-Command", psCommand], {
+        cwd,
+        stdio: ["ignore", "pipe", "inherit"],
+    });
+    let out = "";
+    ps.stdout.on("data", (chunk) => (out += chunk));
+    return new Promise((resolve, reject) => {
+        ps.on("error", reject);
+        ps.on("exit", (code) => {
+            const pid = Number(out.trim());
+            if (code !== 0 || !Number.isInteger(pid)) {
+                reject(new Error(`Failed to launch TRXA Studio via PowerShell (exit ${code}): ${out.trim()}`));
+            }
+            else {
+                resolve(pid);
+            }
+        });
+    });
+}
+/** Opens `url` in the OS default browser, best-effort -- failures just fall back to printing the URL. */
+function openBrowser(url) {
+    try {
+        const child = process.platform === "win32"
+            ? spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" })
+            : process.platform === "darwin"
+                ? spawn("open", [url], { detached: true, stdio: "ignore" })
+                : spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+        child.on("error", () => console.error(`Couldn't auto-open a browser -- visit ${url} manually.`));
+        child.unref();
+    }
+    catch {
+        console.error(`Couldn't auto-open a browser -- visit ${url} manually.`);
+    }
+}
+/** Detects whether this is a real packaged install (`npm run package` has produced a bundled
+ *  production server) versus a dev checkout being driven via `npm run studio`. Checking for the
+ *  bundle's existence, rather than some other signal (e.g. "does `studio/` source exist"), means
+ *  a dev checkout that happens to have run `npm run package` locally also gets the real packaged
+ *  behavior -- useful for testing this exact code path without a real npm install. */
+function packagedStudioServerPath(repoRoot) {
+    const candidate = path.join(repoRoot, "studio", "server", "dist", "index.js");
+    return existsSync(candidate) ? candidate : null;
+}
+async function cmdStudioStart(repoRoot) {
+    const runDir = STUDIO_RUN_DIR;
+    const pidFile = path.join(runDir, "pid");
+    const logFile = path.join(runDir, "log");
+    const packagedServer = packagedStudioServerPath(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 Studio is already running (PID ${existingPid}). Opening ${studioUrl} ...`);
+        openBrowser(studioUrl);
+        return;
+    }
+    await mkdir(runDir, { recursive: true });
+    // A tiny launcher script, not the redirection inlined into a `shell:true` command string --
+    // the latter produced no error but also no log output: Node wraps the whole command in its own
+    // outer quotes for cmd.exe, and cmd's `/S`-flag quote-stripping (triggered by shell:true)
+    // mangles the second, inner pair of quotes around the log path, silently breaking the
+    // redirection while "npm run studio" itself still launched fine. Quotes on a line inside a
+    // script file are parsed normally -- no /S involved.
+    const scriptExt = process.platform === "win32" ? "cmd" : "sh";
+    const scriptPath = path.join(runDir, `launch.${scriptExt}`);
+    // Packaged: run the bundled server directly with `node` -- no `npm run studio`, no Vite dev
+    // server, no devDependencies (tsx/vite/concurrently) needed, none of which a real npm install
+    // has. Dev: unchanged, still delegates to the root `npm run studio` script.
+    const launchCommand = packagedServer ? `node "${packagedServer}"` : "npm run studio";
+    // Packaged only: the *user's* cwd (wherever they actually ran `trxa studio` from), not
+    // `repoRoot` (the installed package's own directory) -- this becomes the working folder's
+    // first-run default (see studio/server/settings.ts), and the package's own install directory is
+    // never a sensible guess for that. Dev keeps `repoRoot` since `npm run studio` must run from
+    // wherever package.json's scripts actually live.
+    const launchCwd = packagedServer ? process.cwd() : repoRoot;
+    const scriptBody = process.platform === "win32"
+        ? `@echo off\r\n${launchCommand} > "${logFile}" 2>&1\r\n`
+        : `#!/bin/sh\n${launchCommand} > "${logFile}" 2>&1\n`;
+    await writeFile(scriptPath, scriptBody, "utf-8");
+    const pid = await launchDetachedScript(scriptPath, launchCwd);
+    await writeFile(pidFile, String(pid), "utf-8");
+    const ready = await waitForServer(studioUrl, 20_000);
+    if (ready) {
+        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 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`);
+    }
+    openBrowser(studioUrl);
+}
+async function cmdStudioStop() {
+    const pidFile = path.join(STUDIO_RUN_DIR, "pid");
+    const pid = await readStudioPid(pidFile);
+    if (pid === null) {
+        console.error("TRXA Studio doesn't appear to be running (no PID file found).");
+        return;
+    }
+    if (!isProcessAlive(pid)) {
+        console.error(`TRXA Studio isn't running (stale PID ${pid}) -- cleaning up.`);
+        await unlink(pidFile).catch(() => { });
+        return;
+    }
+    if (process.platform === "win32") {
+        await new Promise((resolve) => {
+            const killer = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+            killer.on("exit", () => resolve());
+            killer.on("error", () => resolve());
+        });
+    }
+    else {
+        // detached:true made `pid` the leader of its own process group; the negative PID targets the
+        // whole group (concurrently + tsx watch + vite), not just the top npm/shell process.
+        try {
+            process.kill(-pid, "SIGTERM");
+        }
+        catch {
+            process.kill(pid, "SIGTERM");
+        }
+    }
+    await unlink(pidFile).catch(() => { });
+    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`
+ *  script in a dev checkout (that command itself stays foreground/verbose -- still the right mode
+ *  for actual Studio development, e.g. via the Claude_Preview MCP tools) or launches the bundled
+ *  production server directly once `npm run package` has produced one -- see
+ *  `packagedStudioServerPath`/`cmdStudioStart` for how that's detected. */
+async function cmdStudio(args) {
+    if (args[0] === "stop") {
+        await cmdStudioStop();
+    }
+    else {
+        await cmdStudioStart(REPO_ROOT);
+    }
+}
+const COMMAND_GROUPS = [
+    {
+        title: "turn a recording into a test script",
+        commands: [
+            { name: "parse", usage: "<file.axtr> [-o out.testscript.json]", summary: "Parse a .axtr recording into a Test Script", handler: cmdParse },
+            {
+                name: "suggest-inputs",
+                usage: "<file.axtr> [-o draft.json]",
+                summary: "Draft candidate Test Case inputs from a recording",
+                handler: cmdSuggestInputs,
+            },
+        ],
+    },
+    {
+        title: "author & validate test cases, fixtures, suites, plans",
+        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>",
+                summary: "Validate a Test Suite file (also checks DAG order/cycles)",
+                handler: cmdValidateSuite,
+            },
+            { name: "plan-suite", usage: "<suite.json>", summary: "Print a suite's resolved execution order", handler: cmdPlanSuite },
+            {
+                name: "validate-plan",
+                usage: "<plan.json>",
+                summary: "Validate a Test Plan file and every suite it references",
+                handler: cmdValidatePlan,
+            },
+        ],
+    },
+    {
+        title: "set up a project for LLM-driven replay",
+        commands: [
+            {
+                name: "init-skill",
+                usage: "[--force]",
+                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,
+            },
+        ],
+    },
+    {
+        title: "run a suite or plan",
+        commands: [
+            {
+                name: "init-plan-run",
+                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 [--name "<run name>"]',
+                summary: "Create a new Test Run file for a suite, all test cases pending; --name labels the run",
+                handler: cmdInitRun,
+            },
+            {
+                name: "resolve-next",
+                usage: "<suite.json> <testrun.json> --testcases-dir <dir> [--fixtures-dir <dir>]",
+                summary: "Resolve the next runnable test case's inputs",
+                handler: cmdResolveNext,
+            },
+            {
+                name: "measure-tokens",
+                usage: "--since <isoTimestamp> --until <isoTimestamp> [--transcript <path>]",
+                summary: "Sum real token usage from Claude Code's own session log for a time window",
+                handler: cmdMeasureTokens,
+            },
+            {
+                name: "record-result",
+                usage: "<testrun.json> <testCaseId> --status passed|failed|blocked (--outputs '{...}' | --outputs-file <path>) " +
+                    "[--assertions '[...]' | --assertions-file <path>]",
+                summary: "Record a test case's outcome into a Test Run",
+                handler: cmdRecordResult,
+            },
+            {
+                name: "plan-status",
+                usage: "<plan.json> <run.json> --testruns-dir <dir>",
+                summary: "Roll up a Test Plan's status across its suites' Test Runs for one PlanRun",
+                handler: cmdPlanStatus,
+            },
+        ],
+    },
+    {
+        title: "analyze a whole recordings library",
+        commands: [
+            {
+                name: "analyze-library",
+                usage: "<recordingsDir> [--report analysis/library-report.json] [--csv analysis/scrubbed-values.csv]",
+                summary: "Scan a directory of recordings; report structural coverage and gaps",
+                handler: cmdAnalyzeLibrary,
+            },
+        ],
+    },
+    {
+        title: "visual editor",
+        commands: [
+            { name: "studio", usage: "[stop]", summary: "Start (or stop) the Studio web UI", handler: cmdStudio },
+        ],
+    },
+    {
+        title: "back up & migrate a whole library",
+        commands: [
+            {
+                name: "export",
+                usage: "-o <backup.zip>",
+                summary: "Bundle recordings/testcases/testdata/testscripts/suites/plans/testruns into a zip",
+                handler: cmdExport,
+            },
+            {
+                name: "import",
+                usage: "<backup.zip> [--force]",
+                summary: "Unpack a library backup zip (refuses on name collisions unless --force)",
+                handler: cmdImport,
+            },
+        ],
+    },
+];
+const COMMANDS = Object.fromEntries(COMMAND_GROUPS.flatMap((group) => group.commands).map((c) => [c.name, c]));
+async function readPackageVersion(repoRoot) {
+    try {
+        const raw = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf-8"));
+        return raw.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function renderHelp(version) {
+    const nameCol = Math.max(...COMMAND_GROUPS.flatMap((g) => g.commands.map((c) => c.name.length)));
+    const groups = COMMAND_GROUPS.map((group) => {
+        const lines = group.commands.map((c) => `   ${c.name.padEnd(nameCol)}   ${c.summary}`).join("\n");
+        return `${group.title}\n${lines}`;
+    }).join("\n\n");
+    return (`trxa-tool ${version} -- D365 Finance & Operations Task Recorder test automation\n\n` +
+        `Usage: trxa <command> [<args>]\n\n` +
+        `These are the trxa commands, grouped by what they're for:\n\n` +
+        `${groups}\n\n` +
+        `Run 'trxa <command>' with no further arguments to see that command's specific usage.`);
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || command === "help" || command === "-h" || command === "--help") {
+        console.log(renderHelp(await readPackageVersion(REPO_ROOT)));
+        return;
+    }
+    if (command === "-v" || command === "--version") {
+        console.log(`trxa-tool ${await readPackageVersion(REPO_ROOT)}`);
+        return;
+    }
+    const spec = COMMANDS[command];
+    if (!spec) {
+        console.error(`trxa: '${command}' is not a trxa command. See 'trxa help' for the full list.`);
+        process.exitCode = 1;
+        return;
+    }
+    await spec.handler(args);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+});