trxa-tool 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/.claude/skills/replay-trxa-testplan/SKILL.md +627 -0
  2. package/LICENSE +120 -0
  3. package/MANUAL.md +548 -0
  4. package/README.md +67 -3
  5. package/STUDIO.md +319 -0
  6. package/dist/analyze.d.ts +58 -0
  7. package/dist/analyze.js +122 -0
  8. package/dist/bpm.d.ts +40 -0
  9. package/dist/bpm.js +60 -0
  10. package/dist/build-test-script.d.ts +24 -0
  11. package/dist/build-test-script.js +40 -0
  12. package/dist/csv.d.ts +1 -0
  13. package/dist/csv.js +11 -0
  14. package/dist/extract.d.ts +14 -0
  15. package/dist/extract.js +34 -0
  16. package/dist/fixture-schema.d.ts +12 -0
  17. package/dist/fixture-schema.js +28 -0
  18. package/dist/index.d.ts +3 -0
  19. package/dist/index.js +814 -0
  20. package/dist/library-archive.d.ts +37 -0
  21. package/dist/library-archive.js +106 -0
  22. package/dist/mapping.d.ts +25 -0
  23. package/dist/mapping.js +390 -0
  24. package/dist/normalize.d.ts +21 -0
  25. package/dist/normalize.js +43 -0
  26. package/dist/parse.d.ts +3 -0
  27. package/dist/parse.js +233 -0
  28. package/dist/plan-runner.d.ts +27 -0
  29. package/dist/plan-runner.js +36 -0
  30. package/dist/plan-schema.d.ts +27 -0
  31. package/dist/plan-schema.js +45 -0
  32. package/dist/planrun-schema.d.ts +45 -0
  33. package/dist/planrun-schema.js +87 -0
  34. package/dist/planrun.d.ts +20 -0
  35. package/dist/planrun.js +46 -0
  36. package/dist/report-schema.d.ts +83 -0
  37. package/dist/report-schema.js +89 -0
  38. package/dist/report.d.ts +42 -0
  39. package/dist/report.js +70 -0
  40. package/dist/schema.d.ts +96 -0
  41. package/dist/schema.js +10 -0
  42. package/dist/scrub.d.ts +44 -0
  43. package/dist/scrub.js +166 -0
  44. package/dist/suggest-inputs.d.ts +19 -0
  45. package/dist/suggest-inputs.js +92 -0
  46. package/dist/suite-runner.d.ts +59 -0
  47. package/dist/suite-runner.js +198 -0
  48. package/dist/suite-schema.d.ts +59 -0
  49. package/dist/suite-schema.js +95 -0
  50. package/dist/testcase-schema.d.ts +102 -0
  51. package/dist/testcase-schema.js +132 -0
  52. package/dist/token-usage.d.ts +38 -0
  53. package/dist/token-usage.js +95 -0
  54. package/package.json +58 -6
  55. package/studio/client-dist/assets/index-CgWhGkEn.js +24 -0
  56. package/studio/client-dist/assets/index-CwAUMVCL.css +1 -0
  57. package/studio/client-dist/axtr-icon.svg +5 -0
  58. package/studio/client-dist/favicon.svg +5 -0
  59. package/studio/client-dist/index.html +14 -0
  60. package/studio/server/dist/index.js +1938 -0
package/dist/index.js ADDED
@@ -0,0 +1,814 @@
1
+ #!/usr/bin/env node
2
+ import { readFile, writeFile, readdir, mkdir, unlink } from "node:fs/promises";
3
+ import { existsSync } from "node:fs";
4
+ import { spawn } from "node:child_process";
5
+ import path from "node:path";
6
+ import os from "node:os";
7
+ import { fileURLToPath } from "node:url";
8
+ import { loadTestScript, buildTestScript } from "./build-test-script.js";
9
+ import { analyzeLibrary } from "./analyze.js";
10
+ import { toCsv } from "./csv.js";
11
+ import { suggestInputs } from "./suggest-inputs.js";
12
+ import { validateTestCase } from "./testcase-schema.js";
13
+ import { validateFixture } from "./fixture-schema.js";
14
+ import { validateTestSuite } from "./suite-schema.js";
15
+ import { validateTestPlan } from "./plan-schema.js";
16
+ import { topologicalOrder, resolveInputs, nextStep } from "./suite-runner.js";
17
+ import { initTestRun, readTestRun, recordResult } from "./report.js";
18
+ import { initPlanRun, readPlanRun } from "./planrun.js";
19
+ import { aggregatePlanStatus } from "./plan-runner.js";
20
+ import { exportLibrary, importLibrary } from "./library-archive.js";
21
+ import { TERMINAL_STATUSES } from "./report-schema.js";
22
+ import { defaultClaudeProjectsRoot, findLatestTranscript, measureTokens } from "./token-usage.js";
23
+ export { loadTestScript, buildTestScript };
24
+ /**
25
+ * Assumes the compiled entry file (this file, once built) sits exactly one directory below the
26
+ * repo root -- true for `dist/index.js` per `tsconfig.json`'s `outDir`, but silent if that layout
27
+ * ever changes (e.g. a nested `dist/src/index.js`): `studio start`/`stop` and the version lookup
28
+ * would then resolve the wrong directory with no error, since `path.resolve` doesn't validate
29
+ * what it points at. Computed once here (was previously duplicated in `cmdStudio` and `main`).
30
+ */
31
+ const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
32
+ function flagValue(args, name) {
33
+ const i = args.indexOf(name);
34
+ return i >= 0 ? args[i + 1] ?? null : null;
35
+ }
36
+ /** Reads a JSON-valued flag that accepts either an inline string (e.g. `--outputs '{"a":"b"}'`) or
37
+ * a file path (`--outputs-file path/to.json`). The file form exists to sidestep shell-specific
38
+ * argv-quoting bugs, not just as a convenience for long payloads: Windows PowerShell 5.1's
39
+ * argument-passing layer to a native executable (node.exe isn't a cmdlet) can silently corrupt
40
+ * inline JSON containing quote characters and/or spaces before Node ever sees `process.argv` --
41
+ * see POWERSHELL-JSON-ARGS.md for two distinct reproduced failure modes and why a `--%`-plus-
42
+ * escaping workaround was needed before this flag existed. Throws if both forms are passed rather
43
+ * than silently preferring one, since that's more likely a caller mistake than an intentional
44
+ * choice. */
45
+ async function jsonFlagValue(rest, inlineFlag, fileFlag) {
46
+ const inline = flagValue(rest, inlineFlag);
47
+ const filePath = flagValue(rest, fileFlag);
48
+ if (inline !== null && filePath !== null) {
49
+ throw new Error(`Pass either ${inlineFlag} or ${fileFlag}, not both`);
50
+ }
51
+ if (filePath !== null)
52
+ return JSON.parse(await readFile(filePath, "utf-8"));
53
+ if (inline !== null)
54
+ return JSON.parse(inline);
55
+ return undefined;
56
+ }
57
+ async function outputJson(value, outPath, successMessage) {
58
+ const json = JSON.stringify(value, null, 2);
59
+ if (outPath) {
60
+ await writeFile(outPath, json, "utf-8");
61
+ console.error(successMessage);
62
+ }
63
+ else {
64
+ console.log(json);
65
+ }
66
+ }
67
+ async function loadTestCaseFile(testcasesDir, testCaseId) {
68
+ const filePath = path.join(testcasesDir, `${testCaseId}.json`);
69
+ const raw = JSON.parse(await readFile(filePath, "utf-8"));
70
+ return validateTestCase(raw);
71
+ }
72
+ /** `--fixtures-dir` is optional at the CLI level (see `resolve-next`'s usage) -- if omitted, this
73
+ * function is never called at all and `fixtures` is just `[]`. This catch only fires when the
74
+ * flag *was* passed but the directory doesn't exist, and it's deliberately treated the same as
75
+ * "empty directory" rather than a hard error: a suite that binds nothing via `fixture` kind
76
+ * doesn't need one to exist. The tradeoff is a mistyped `--fixtures-dir` path silently produces
77
+ * zero fixtures instead of an error naming the bad path -- the first symptom a reviewer sees is
78
+ * `suite-runner.ts`'s later, less specific "no fixture named X found". */
79
+ async function loadFixtures(fixturesDir) {
80
+ let entries;
81
+ try {
82
+ entries = await readdir(fixturesDir);
83
+ }
84
+ catch {
85
+ return [];
86
+ }
87
+ const fixtures = [];
88
+ for (const entry of entries) {
89
+ if (!entry.endsWith(".json"))
90
+ continue;
91
+ const raw = JSON.parse(await readFile(path.join(fixturesDir, entry), "utf-8"));
92
+ fixtures.push(validateFixture(raw));
93
+ }
94
+ return fixtures;
95
+ }
96
+ async function loadSuite(suitePath) {
97
+ const raw = JSON.parse(await readFile(suitePath, "utf-8"));
98
+ return validateTestSuite(raw);
99
+ }
100
+ async function loadPlan(planPath) {
101
+ const raw = JSON.parse(await readFile(planPath, "utf-8"));
102
+ return validateTestPlan(raw);
103
+ }
104
+ // --- Commands ---
105
+ async function cmdParse(args) {
106
+ const [inputPath, ...rest] = args;
107
+ if (!inputPath) {
108
+ throw new Error("Usage: trxa parse <file.axtr> [-o out.testscript.json]");
109
+ }
110
+ const outPath = flagValue(rest, "-o");
111
+ const testScript = await buildTestScript(inputPath);
112
+ await outputJson(testScript, outPath, `Wrote ${testScript.steps.length} steps to ${outPath}`);
113
+ }
114
+ async function cmdSuggestInputs(args) {
115
+ const [inputPath, ...rest] = args;
116
+ if (!inputPath) {
117
+ throw new Error("Usage: trxa suggest-inputs <file.axtr> [-o draft.json]");
118
+ }
119
+ const outPath = flagValue(rest, "-o");
120
+ const script = await loadTestScript(inputPath);
121
+ const draft = suggestInputs(script);
122
+ await outputJson(draft, outPath, `Wrote ${draft.candidates.length} candidate inputs to ${outPath}`);
123
+ }
124
+ async function cmdValidateTestCase(args) {
125
+ const [filePath] = args;
126
+ if (!filePath)
127
+ throw new Error("Usage: trxa validate-testcase <testcase.json>");
128
+ const raw = JSON.parse(await readFile(filePath, "utf-8"));
129
+ const testCase = validateTestCase(raw);
130
+ console.error(`OK: "${testCase.id}" is a valid test case (${testCase.inputs.length} inputs, ${testCase.expectations.length} expectations)`);
131
+ }
132
+ async function cmdValidateFixture(args) {
133
+ const [filePath] = args;
134
+ if (!filePath)
135
+ throw new Error("Usage: trxa validate-fixture <fixture.json>");
136
+ const raw = JSON.parse(await readFile(filePath, "utf-8"));
137
+ const fixture = validateFixture(raw);
138
+ console.error(`OK: "${fixture.name}" is a valid fixture for test case "${fixture.testCaseId}"`);
139
+ }
140
+ async function cmdValidateSuite(args) {
141
+ const [filePath] = args;
142
+ if (!filePath)
143
+ throw new Error("Usage: trxa validate-suite <suite.json>");
144
+ const suite = await loadSuite(filePath);
145
+ const order = topologicalOrder(suite); // also catches cycles/unknown dependsOn ids
146
+ console.error(`OK: "${suite.id}" is a valid suite (${order.length} entries, execution order: ${order.join(" -> ")})`);
147
+ }
148
+ async function cmdPlanSuite(args) {
149
+ const [suitePath] = args;
150
+ if (!suitePath)
151
+ throw new Error("Usage: trxa plan-suite <suite.json>");
152
+ const suite = await loadSuite(suitePath);
153
+ const order = topologicalOrder(suite);
154
+ console.log(JSON.stringify({ suiteId: suite.id, executionOrder: order }, null, 2));
155
+ }
156
+ /** Relative to `REPO_ROOT` (where the bundled copy ships from -- see package.json's `files`). The
157
+ * canonical source lives under the Claude Code path since that's this repo's own dev-time
158
+ * convention too -- both agent tools' SKILL.md format (frontmatter `name`/`description`) is
159
+ * identical, only the containing directory each tool scans differs, so one source file gets
160
+ * copied verbatim to every target below rather than maintained twice. */
161
+ const SKILL_SOURCE_RELATIVE_PATH = path.join(".claude", "skills", "replay-trxa-testplan", "SKILL.md");
162
+ /** Every location an agent tool discovers a project-scoped skill from, not from anywhere inside an
163
+ * installed npm package's own `node_modules` -- so shipping the file in the package alone doesn't
164
+ * make any of these tools find it. This command bridges that gap explicitly, same "customer says
165
+ * where, nothing writes outside their project on its own" philosophy as Studio's working-folder
166
+ * setting. Add an entry here, not a new command, if another tool's convention needs supporting. */
167
+ const SKILL_INSTALL_TARGETS = [
168
+ { tool: "Claude Code", relativePath: path.join(".claude", "skills", "replay-trxa-testplan", "SKILL.md") },
169
+ { tool: "Codex", relativePath: path.join(".agents", "skills", "replay-trxa-testplan", "SKILL.md") },
170
+ ];
171
+ async function cmdInitSkill(args) {
172
+ const force = args.includes("--force");
173
+ const sourcePath = path.join(REPO_ROOT, SKILL_SOURCE_RELATIVE_PATH);
174
+ if (!existsSync(sourcePath)) {
175
+ throw new Error(`Bundled skill file not found at ${sourcePath} -- this install may be missing it.`);
176
+ }
177
+ const alreadyExisting = SKILL_INSTALL_TARGETS.filter((t) => existsSync(path.join(process.cwd(), t.relativePath)));
178
+ if (alreadyExisting.length > 0 && !force) {
179
+ throw new Error(`Refusing to overwrite existing file(s): ${alreadyExisting.map((t) => t.relativePath).join(", ")} ` +
180
+ `(pass --force to overwrite)`);
181
+ }
182
+ const content = await readFile(sourcePath, "utf-8");
183
+ for (const target of SKILL_INSTALL_TARGETS) {
184
+ const destPath = path.join(process.cwd(), target.relativePath);
185
+ await mkdir(path.dirname(destPath), { recursive: true });
186
+ await writeFile(destPath, content, "utf-8");
187
+ }
188
+ console.error(`Installed the replay-trxa-testplan skill for ${SKILL_INSTALL_TARGETS.map((t) => t.tool).join(" and ")} ` +
189
+ `(${SKILL_INSTALL_TARGETS.map((t) => t.relativePath).join(", ")}) -- each tool will pick it up ` +
190
+ `automatically the next time it runs in this project.`);
191
+ }
192
+ async function cmdInitRun(args) {
193
+ const [suitePath, ...rest] = args;
194
+ const outPath = flagValue(rest, "-o");
195
+ if (!suitePath || !outPath) {
196
+ throw new Error("Usage: trxa init-run <suite.json> -o testruns/<suiteId>-<runId>.json");
197
+ }
198
+ const suite = await loadSuite(suitePath);
199
+ const testRun = await initTestRun(suite, outPath);
200
+ console.error(`Initialized test run for suite "${suite.id}" (${Object.keys(testRun.results).length} test cases, all pending) at ${outPath}`);
201
+ }
202
+ async function cmdInitPlanRun(args) {
203
+ const [planPath, ...rest] = args;
204
+ const outDir = flagValue(rest, "-o");
205
+ if (!planPath || !outDir) {
206
+ throw new Error("Usage: trxa init-plan-run <plan.json> -o runs/");
207
+ }
208
+ const plan = await loadPlan(planPath);
209
+ const planDir = path.dirname(planPath);
210
+ const suites = await Promise.all(plan.suites.map(async (entry) => {
211
+ const suite = await loadSuite(path.resolve(planDir, entry.suitePath));
212
+ return { id: suite.id, name: suite.name };
213
+ }));
214
+ const { planRun, filePath } = await initPlanRun(plan.id, suites, outDir);
215
+ console.error(`Initialized plan run "${planRun.id}" for plan "${plan.id}" at ${filePath}`);
216
+ console.log(JSON.stringify(planRun, null, 2));
217
+ }
218
+ async function cmdResolveNext(args) {
219
+ const [suitePath, testRunPath, ...rest] = args;
220
+ const testcasesDir = flagValue(rest, "--testcases-dir");
221
+ const fixturesDir = flagValue(rest, "--fixtures-dir");
222
+ if (!suitePath || !testRunPath || !testcasesDir) {
223
+ throw new Error("Usage: trxa resolve-next <suite.json> <testrun.json> --testcases-dir <dir> [--fixtures-dir <dir>]");
224
+ }
225
+ const suite = await loadSuite(suitePath);
226
+ const testRun = await readTestRun(testRunPath);
227
+ const progress = nextStep(suite, testRun);
228
+ if (progress.status === "newly-blocked") {
229
+ for (const id of progress.blockedIds) {
230
+ await recordResult(testRunPath, id, { status: "blocked" });
231
+ }
232
+ console.log(JSON.stringify({ status: "blocked", blockedIds: progress.blockedIds }, null, 2));
233
+ return;
234
+ }
235
+ if (progress.status === "newly-skipped") {
236
+ for (const id of progress.skippedIds) {
237
+ await recordResult(testRunPath, id, { status: "skipped" });
238
+ }
239
+ console.log(JSON.stringify({ status: "skipped", skippedIds: progress.skippedIds }, null, 2));
240
+ return;
241
+ }
242
+ if (progress.status === "waiting" || progress.status === "complete") {
243
+ console.log(JSON.stringify({ status: progress.status }, null, 2));
244
+ return;
245
+ }
246
+ // Two passes, deliberately not one: resolving a batch of two or more entries can partially fail
247
+ // (e.g. one entry's inputBindings are incomplete, confirmed live with a 3-way branch during
248
+ // development) -- if resolution and the "running" transition were interleaved in a single loop,
249
+ // an entry resolved earlier in the batch would already be persisted as "running" by the time a
250
+ // later one throws, leaving the TestRun file half-committed with no way to recover that entry
251
+ // (it's no longer "pending", so a retried resolve-next won't offer it again, but it never reached
252
+ // a terminal status either). Resolving every entry first, with no side effects, and only starting
253
+ // to write "running" transitions once the whole batch has resolved cleanly, keeps the single-entry
254
+ // case's original atomicity guarantee (a throw here means nothing gets persisted) intact even when
255
+ // `progress.testCaseIds` has more than one id in it.
256
+ const resolved = progress.testCaseIds.map((testCaseId) => {
257
+ const entry = suite.entries.find((e) => e.testCaseId === testCaseId);
258
+ return { testCaseId, entry };
259
+ });
260
+ const fixtures = fixturesDir ? await loadFixtures(fixturesDir) : [];
261
+ const toRun = await Promise.all(resolved.map(async ({ testCaseId, entry }) => {
262
+ const testCase = await loadTestCaseFile(testcasesDir, testCaseId);
263
+ const resolvedInputs = resolveInputs(entry, testCase, testRun, fixtures);
264
+ // `resolveInputs` deliberately leaves "autogenerated" params unresolved -- surface them here
265
+ // (with the param's own description/example as generation guidance) rather than in the pure
266
+ // resolver, since inventing a value is the orchestrating LLM's job, not this CLI's.
267
+ const autogeneratedParams = testCase.inputs
268
+ .filter((p) => entry.inputBindings[p.name]?.kind === "autogenerated")
269
+ .map((p) => ({ name: p.name, description: p.description, example: p.example }));
270
+ return { testCaseId, entry, testCase, resolvedInputs, autogeneratedParams };
271
+ }));
272
+ // Sequential, not Promise.all -- each recordResult call does its own read-modify-write of the
273
+ // same testRunPath file, so writing them concurrently would risk one overwriting another's
274
+ // "running" transition. By this point every entry has already resolved successfully, so this
275
+ // loop itself can't fail partway through for a data reason -- only a filesystem-level failure
276
+ // could leave it partially applied, the same exposure `record-result` already has today.
277
+ const runnable = [];
278
+ for (const { testCaseId, entry, testCase, resolvedInputs, autogeneratedParams } of toRun) {
279
+ await recordResult(testRunPath, testCaseId, { status: "running", inputs: resolvedInputs });
280
+ runnable.push({
281
+ testCaseId,
282
+ testScriptPath: testCase.testScriptPath,
283
+ legalEntity: entry.legalEntity,
284
+ resolvedInputs,
285
+ autogeneratedParams,
286
+ outputs: testCase.outputs,
287
+ expectations: testCase.expectations,
288
+ });
289
+ }
290
+ console.log(JSON.stringify({ status: "runnable", runnable }, null, 2));
291
+ }
292
+ async function cmdRecordResult(args) {
293
+ const [testRunPath, testCaseId, ...rest] = args;
294
+ const status = flagValue(rest, "--status");
295
+ const tokensRaw = flagValue(rest, "--tokens");
296
+ const costRaw = flagValue(rest, "--cost");
297
+ if (!testRunPath || !testCaseId || !status) {
298
+ throw new Error('Usage: trxa record-result <testrun.json> <testCaseId> --status passed|failed|blocked ' +
299
+ '(--outputs \'{"name":"value"}\' | --outputs-file <path>) ' +
300
+ "[--assertions '[{\"description\":\"...\",\"passed\":true,\"actual\":\"...\"}]' | --assertions-file <path>] " +
301
+ '[--inputs \'{"name":"value"}\' | --inputs-file <path>] ' +
302
+ "[--tokens <number>] (auto-measured from Claude Code's session log if omitted) [--cost <usd>] " +
303
+ "[--messages '[\"...\"]' | --messages-file <path>]. " +
304
+ "The *-file flags read JSON from a file instead of argv -- prefer them on Windows PowerShell, whose " +
305
+ "argument-passing layer can corrupt inline JSON containing quotes/spaces (see MANUAL.md, Windows PowerShell section).");
306
+ }
307
+ const outputs = await jsonFlagValue(rest, "--outputs", "--outputs-file");
308
+ const assertionResults = await jsonFlagValue(rest, "--assertions", "--assertions-file");
309
+ const inputs = await jsonFlagValue(rest, "--inputs", "--inputs-file");
310
+ const costUsd = costRaw ? Number(costRaw) : undefined;
311
+ const messages = await jsonFlagValue(rest, "--messages", "--messages-file");
312
+ // Auto-measure real token usage from Claude Code's own session log when the caller didn't pass
313
+ // an explicit number and this result is reaching a terminal status with a known start time --
314
+ // no separate step for the orchestrating LLM to remember. An explicit --tokens still wins (e.g.
315
+ // a future execution mode with a better source), and this is skipped silently -- not an error --
316
+ // if no transcript can be found (see findLatestTranscript's own caveat about concurrent sessions).
317
+ let tokensUsed = tokensRaw ? Number(tokensRaw) : undefined;
318
+ if (tokensUsed === undefined && TERMINAL_STATUSES.has(status)) {
319
+ const existingRun = await readTestRun(testRunPath);
320
+ const startedAt = existingRun.results[testCaseId]?.startedAt;
321
+ if (startedAt) {
322
+ const transcriptPath = findLatestTranscript(defaultClaudeProjectsRoot());
323
+ if (transcriptPath) {
324
+ tokensUsed = measureTokens(transcriptPath, startedAt, new Date().toISOString());
325
+ }
326
+ }
327
+ }
328
+ const testRun = await recordResult(testRunPath, testCaseId, {
329
+ status,
330
+ outputs,
331
+ assertionResults,
332
+ inputs,
333
+ tokensUsed,
334
+ costUsd,
335
+ messages,
336
+ });
337
+ console.error(`Recorded "${testCaseId}" as ${status} in ${testRunPath}`);
338
+ console.log(JSON.stringify(testRun.results[testCaseId], null, 2));
339
+ }
340
+ async function cmdMeasureTokens(args) {
341
+ const since = flagValue(args, "--since");
342
+ const until = flagValue(args, "--until");
343
+ const transcriptOverride = flagValue(args, "--transcript");
344
+ if (!since || !until) {
345
+ throw new Error("Usage: trxa measure-tokens --since <isoTimestamp> --until <isoTimestamp> [--transcript <path>]");
346
+ }
347
+ const transcriptPath = transcriptOverride ?? findLatestTranscript(defaultClaudeProjectsRoot());
348
+ if (!transcriptPath) {
349
+ console.log(JSON.stringify({ tokensUsed: null, transcriptPath: null, reason: "no Claude Code session transcript found" }, null, 2));
350
+ return;
351
+ }
352
+ const tokensUsed = measureTokens(transcriptPath, since, until);
353
+ console.log(JSON.stringify({ tokensUsed, transcriptPath }, null, 2));
354
+ }
355
+ async function cmdValidatePlan(args) {
356
+ const [planPath] = args;
357
+ if (!planPath)
358
+ throw new Error("Usage: trxa validate-plan <plan.json>");
359
+ const plan = await loadPlan(planPath);
360
+ const planDir = path.dirname(planPath);
361
+ for (const entry of plan.suites) {
362
+ const resolvedSuitePath = path.resolve(planDir, entry.suitePath);
363
+ const suite = await loadSuite(resolvedSuitePath);
364
+ if (suite.id !== entry.suiteId) {
365
+ throw new Error(`Plan "${plan.id}": entry declares suiteId "${entry.suiteId}" but ${entry.suitePath} has id "${suite.id}"`);
366
+ }
367
+ topologicalOrder(suite); // catches cycles/unknown dependsOn ids within that suite
368
+ }
369
+ console.error(`OK: "${plan.id}" is a valid plan (${plan.suites.length} suites, all resolve and validate)`);
370
+ }
371
+ async function cmdPlanStatus(args) {
372
+ const [planPath, runPath, ...rest] = args;
373
+ const testrunsDir = flagValue(rest, "--testruns-dir");
374
+ if (!planPath || !runPath || !testrunsDir) {
375
+ throw new Error("Usage: trxa plan-status <plan.json> <run.json> --testruns-dir <dir>");
376
+ }
377
+ const plan = await loadPlan(planPath);
378
+ const run = await readPlanRun(runPath);
379
+ if (run.planId !== plan.id) {
380
+ throw new Error(`Plan run at ${runPath} belongs to plan "${run.planId}", not "${plan.id}"`);
381
+ }
382
+ const testRuns = new Map();
383
+ for (const suiteId of run.suiteIds) {
384
+ const testRunPath = path.join(testrunsDir, `${suiteId}-${run.id}.json`);
385
+ try {
386
+ testRuns.set(suiteId, await readTestRun(testRunPath));
387
+ }
388
+ catch {
389
+ testRuns.set(suiteId, null);
390
+ }
391
+ }
392
+ const status = aggregatePlanStatus(run, testRuns);
393
+ console.log(JSON.stringify({ ...status, startedAt: run.startedAt }, null, 2));
394
+ }
395
+ async function cmdAnalyzeLibrary(args) {
396
+ const [recordingsDir, ...rest] = args;
397
+ if (!recordingsDir) {
398
+ throw new Error("Usage: trxa analyze-library <recordingsDir> [--report analysis/library-report.json] [--csv analysis/scrubbed-values.csv]");
399
+ }
400
+ const reportPath = flagValue(rest, "--report") ?? "analysis/library-report.json";
401
+ const csvPath = flagValue(rest, "--csv") ?? "analysis/scrubbed-values.csv";
402
+ const { report, scrubbedValues } = await analyzeLibrary(recordingsDir);
403
+ await mkdir(path.dirname(reportPath), { recursive: true });
404
+ await mkdir(path.dirname(csvPath), { recursive: true });
405
+ await writeFile(reportPath, JSON.stringify(report, null, 2), "utf-8");
406
+ await writeFile(csvPath, toCsv(["recordingFile", "recordingName", "nodeKind", "nodeId", "globalId", "sequence", "fieldPath", "token", "originalValue"], scrubbedValues.map((v) => [
407
+ v.recordingFile,
408
+ v.recordingName,
409
+ v.nodeKind,
410
+ v.nodeId,
411
+ v.globalId ?? "",
412
+ String(v.sequence),
413
+ v.fieldPath,
414
+ v.token,
415
+ v.originalValue,
416
+ ])), "utf-8");
417
+ console.error(`Analyzed ${report.recordingsAnalyzed} recording(s) (${report.parseErrors.length} parse error(s)).\n` +
418
+ ` Structural report (scrubbed, safe to share/review): ${reportPath}\n` +
419
+ ` Scrubbed-value mapping (CONTAINS REAL BUSINESS DATA -- local only, never share/commit): ${csvPath} (${scrubbedValues.length} value(s))`);
420
+ }
421
+ async function cmdExport(args) {
422
+ const outPath = flagValue(args, "-o");
423
+ if (!outPath) {
424
+ throw new Error("Usage: trxa export -o <backup.zip>");
425
+ }
426
+ const result = await exportLibrary(process.cwd(), outPath);
427
+ console.error(`Exported ${result.fileCount} file(s) from ${result.dirs.join(", ")} to ${result.outPath}`);
428
+ }
429
+ async function cmdImport(args) {
430
+ const [zipPath, ...rest] = args;
431
+ const force = rest.includes("--force");
432
+ if (!zipPath) {
433
+ throw new Error("Usage: trxa import <backup.zip> [--force]");
434
+ }
435
+ const result = await importLibrary(zipPath, process.cwd(), force);
436
+ if (result.collisions.length > 0) {
437
+ throw new Error(`Refusing to import: ${result.collisions.length} file(s) already exist and would be overwritten (pass --force to overwrite):\n` +
438
+ result.collisions.map((c) => ` ${c}`).join("\n"));
439
+ }
440
+ console.error(`Imported ${result.fileCount} file(s) from ${zipPath}`);
441
+ }
442
+ const STUDIO_URL = "http://localhost:5173/";
443
+ /** Home-directory-based, not `repoRoot`-relative -- same reasoning as `studio/server/paths.ts`'s
444
+ * WORKING_FOLDER (see that file): a real installed package's own directory isn't a stable place
445
+ * to keep runtime state like a PID/log file, since it can be wiped on upgrade or need elevated
446
+ * permissions to write to. This is state about the *running Studio process*, not project data, so
447
+ * it lives next to (not inside) the per-user config `studio/server/settings.ts` also writes to
448
+ * `~/.trxa-tool/`. */
449
+ const STUDIO_RUN_DIR = path.join(os.homedir(), ".trxa-tool", "studio-run");
450
+ /** Checks whether `pid` names a currently-running process, without sending a real signal. */
451
+ function isProcessAlive(pid) {
452
+ try {
453
+ process.kill(pid, 0);
454
+ return true;
455
+ }
456
+ catch {
457
+ return false;
458
+ }
459
+ }
460
+ async function readStudioPid(pidFile) {
461
+ try {
462
+ const raw = (await readFile(pidFile, "utf-8")).trim();
463
+ const pid = Number(raw);
464
+ return Number.isInteger(pid) && pid > 0 ? pid : null;
465
+ }
466
+ catch {
467
+ return null;
468
+ }
469
+ }
470
+ /** Polls `url` until it responds (any status) or `timeoutMs` elapses. Returns whether it answered. */
471
+ async function waitForServer(url, timeoutMs) {
472
+ const deadline = Date.now() + timeoutMs;
473
+ while (Date.now() < deadline) {
474
+ try {
475
+ await fetch(url);
476
+ return true;
477
+ }
478
+ catch {
479
+ // not up yet -- connection refused, still starting
480
+ }
481
+ await new Promise((resolve) => setTimeout(resolve, 400));
482
+ }
483
+ return false;
484
+ }
485
+ /**
486
+ * Runs `scriptPath` fully detached from this short-lived CLI process (survives it exiting),
487
+ * returning the PID of the actual long-running process so `studio stop` can target it later.
488
+ *
489
+ * Windows needs a different mechanism than POSIX here. `spawn("cmd", ["/c", scriptPath], {
490
+ * detached: true, stdio: "inherit" })` looked right -- no error, correct exit code, the script
491
+ * genuinely ran (confirmed with plain cmd.exe builtins like `echo`) -- but silently dropped
492
+ * stdout specifically from any nested node.exe process: even bare `npm --version` (no
493
+ * concurrently/vite/tsx involved) lost its output while still reporting exit code 0. Something
494
+ * about the CREATE_NEW_PROCESS_GROUP flag Node sets for `detached: true` on Windows breaks stdio
495
+ * inheritance for node.exe grandchildren specifically. Routing through PowerShell's
496
+ * `Start-Process -PassThru` instead sidesteps it entirely (confirmed live: full
497
+ * concurrently/vite/tsx startup output lands in the log correctly, and the returned PID's whole
498
+ * process tree -- 16 processes deep in testing -- dies cleanly via `taskkill /T /F`).
499
+ */
500
+ async function launchDetachedScript(scriptPath, cwd) {
501
+ if (process.platform !== "win32") {
502
+ const child = spawn("/bin/sh", [scriptPath], { cwd, detached: true, stdio: "ignore" });
503
+ child.unref();
504
+ if (!child.pid)
505
+ throw new Error("Failed to start trxa-tool Studio (no PID returned)");
506
+ return child.pid;
507
+ }
508
+ const psCommand = `$p = Start-Process -FilePath 'cmd.exe' -ArgumentList '/c','${scriptPath}' ` +
509
+ `-WorkingDirectory '${cwd}' -WindowStyle Hidden -PassThru; Write-Output $p.Id`;
510
+ const ps = spawn("powershell", ["-NoProfile", "-Command", psCommand], {
511
+ cwd,
512
+ stdio: ["ignore", "pipe", "inherit"],
513
+ });
514
+ let out = "";
515
+ ps.stdout.on("data", (chunk) => (out += chunk));
516
+ return new Promise((resolve, reject) => {
517
+ ps.on("error", reject);
518
+ ps.on("exit", (code) => {
519
+ const pid = Number(out.trim());
520
+ if (code !== 0 || !Number.isInteger(pid)) {
521
+ reject(new Error(`Failed to launch trxa-tool Studio via PowerShell (exit ${code}): ${out.trim()}`));
522
+ }
523
+ else {
524
+ resolve(pid);
525
+ }
526
+ });
527
+ });
528
+ }
529
+ /** Opens `url` in the OS default browser, best-effort -- failures just fall back to printing the URL. */
530
+ function openBrowser(url) {
531
+ try {
532
+ const child = process.platform === "win32"
533
+ ? spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" })
534
+ : process.platform === "darwin"
535
+ ? spawn("open", [url], { detached: true, stdio: "ignore" })
536
+ : spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
537
+ child.on("error", () => console.error(`Couldn't auto-open a browser -- visit ${url} manually.`));
538
+ child.unref();
539
+ }
540
+ catch {
541
+ console.error(`Couldn't auto-open a browser -- visit ${url} manually.`);
542
+ }
543
+ }
544
+ /** Detects whether this is a real packaged install (`npm run package` has produced a bundled
545
+ * production server) versus a dev checkout being driven via `npm run studio`. Checking for the
546
+ * bundle's existence, rather than some other signal (e.g. "does `studio/` source exist"), means
547
+ * a dev checkout that happens to have run `npm run package` locally also gets the real packaged
548
+ * behavior -- useful for testing this exact code path without a real npm install. */
549
+ function packagedStudioServerPath(repoRoot) {
550
+ const candidate = path.join(repoRoot, "studio", "server", "dist", "index.js");
551
+ return existsSync(candidate) ? candidate : null;
552
+ }
553
+ async function cmdStudioStart(repoRoot) {
554
+ const runDir = STUDIO_RUN_DIR;
555
+ const pidFile = path.join(runDir, "pid");
556
+ const logFile = path.join(runDir, "log");
557
+ const packagedServer = packagedStudioServerPath(repoRoot);
558
+ const studioUrl = packagedServer ? `http://127.0.0.1:${process.env.STUDIO_SERVER_PORT ?? 4321}/` : STUDIO_URL;
559
+ const existingPid = await readStudioPid(pidFile);
560
+ if (existingPid !== null && isProcessAlive(existingPid)) {
561
+ console.error(`trxa-tool Studio is already running (PID ${existingPid}). Opening ${studioUrl} ...`);
562
+ openBrowser(studioUrl);
563
+ return;
564
+ }
565
+ await mkdir(runDir, { recursive: true });
566
+ // A tiny launcher script, not the redirection inlined into a `shell:true` command string --
567
+ // the latter produced no error but also no log output: Node wraps the whole command in its own
568
+ // outer quotes for cmd.exe, and cmd's `/S`-flag quote-stripping (triggered by shell:true)
569
+ // mangles the second, inner pair of quotes around the log path, silently breaking the
570
+ // redirection while "npm run studio" itself still launched fine. Quotes on a line inside a
571
+ // script file are parsed normally -- no /S involved.
572
+ const scriptExt = process.platform === "win32" ? "cmd" : "sh";
573
+ const scriptPath = path.join(runDir, `launch.${scriptExt}`);
574
+ // Packaged: run the bundled server directly with `node` -- no `npm run studio`, no Vite dev
575
+ // server, no devDependencies (tsx/vite/concurrently) needed, none of which a real npm install
576
+ // has. Dev: unchanged, still delegates to the root `npm run studio` script.
577
+ const launchCommand = packagedServer ? `node "${packagedServer}"` : "npm run studio";
578
+ // Packaged only: the *user's* cwd (wherever they actually ran `trxa studio` from), not
579
+ // `repoRoot` (the installed package's own directory) -- this becomes the working folder's
580
+ // first-run default (see studio/server/settings.ts), and the package's own install directory is
581
+ // never a sensible guess for that. Dev keeps `repoRoot` since `npm run studio` must run from
582
+ // wherever package.json's scripts actually live.
583
+ const launchCwd = packagedServer ? process.cwd() : repoRoot;
584
+ const scriptBody = process.platform === "win32"
585
+ ? `@echo off\r\n${launchCommand} > "${logFile}" 2>&1\r\n`
586
+ : `#!/bin/sh\n${launchCommand} > "${logFile}" 2>&1\n`;
587
+ await writeFile(scriptPath, scriptBody, "utf-8");
588
+ const pid = await launchDetachedScript(scriptPath, launchCwd);
589
+ await writeFile(pidFile, String(pid), "utf-8");
590
+ const ready = await waitForServer(studioUrl, 20_000);
591
+ if (ready) {
592
+ console.error(`trxa-tool Studio is running in the background (PID ${pid}).\n` +
593
+ ` UI: ${studioUrl}\n` +
594
+ ` Logs: ${logFile}\n` +
595
+ ` Stop: trxa studio stop`);
596
+ }
597
+ else {
598
+ console.error(`trxa-tool Studio (PID ${pid}) is taking longer than expected to come up -- check ${logFile}.\n` +
599
+ ` Opening ${studioUrl} anyway; refresh if it's not ready yet.\n` +
600
+ ` Stop: trxa studio stop`);
601
+ }
602
+ openBrowser(studioUrl);
603
+ }
604
+ async function cmdStudioStop() {
605
+ const pidFile = path.join(STUDIO_RUN_DIR, "pid");
606
+ const pid = await readStudioPid(pidFile);
607
+ if (pid === null) {
608
+ console.error("trxa-tool Studio doesn't appear to be running (no PID file found).");
609
+ return;
610
+ }
611
+ if (!isProcessAlive(pid)) {
612
+ console.error(`trxa-tool Studio isn't running (stale PID ${pid}) -- cleaning up.`);
613
+ await unlink(pidFile).catch(() => { });
614
+ return;
615
+ }
616
+ if (process.platform === "win32") {
617
+ await new Promise((resolve) => {
618
+ const killer = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
619
+ killer.on("exit", () => resolve());
620
+ killer.on("error", () => resolve());
621
+ });
622
+ }
623
+ else {
624
+ // detached:true made `pid` the leader of its own process group; the negative PID targets the
625
+ // whole group (concurrently + tsx watch + vite), not just the top npm/shell process.
626
+ try {
627
+ process.kill(-pid, "SIGTERM");
628
+ }
629
+ catch {
630
+ process.kill(pid, "SIGTERM");
631
+ }
632
+ }
633
+ await unlink(pidFile).catch(() => { });
634
+ console.error(`Stopped trxa-tool Studio (was PID ${pid}).`);
635
+ }
636
+ /** Launches (or stops) the Studio server+client, detached and backgrounded so `trxa studio`
637
+ * returns control immediately and auto-opens the browser. Delegates to the root `npm run studio`
638
+ * script in a dev checkout (that command itself stays foreground/verbose -- still the right mode
639
+ * for actual Studio development, e.g. via the Claude_Preview MCP tools) or launches the bundled
640
+ * production server directly once `npm run package` has produced one -- see
641
+ * `packagedStudioServerPath`/`cmdStudioStart` for how that's detected. */
642
+ async function cmdStudio(args) {
643
+ if (args[0] === "stop") {
644
+ await cmdStudioStop();
645
+ }
646
+ else {
647
+ await cmdStudioStart(REPO_ROOT);
648
+ }
649
+ }
650
+ const COMMAND_GROUPS = [
651
+ {
652
+ title: "turn a recording into a test script",
653
+ commands: [
654
+ { name: "parse", usage: "<file.axtr> [-o out.testscript.json]", summary: "Parse a .axtr recording into a Test Script", handler: cmdParse },
655
+ {
656
+ name: "suggest-inputs",
657
+ usage: "<file.axtr> [-o draft.json]",
658
+ summary: "Draft candidate Test Case inputs from a recording",
659
+ handler: cmdSuggestInputs,
660
+ },
661
+ ],
662
+ },
663
+ {
664
+ title: "author & validate test cases, fixtures, suites, plans",
665
+ commands: [
666
+ { name: "validate-testcase", usage: "<testcase.json>", summary: "Validate a Test Case file", handler: cmdValidateTestCase },
667
+ { name: "validate-fixture", usage: "<fixture.json>", summary: "Validate a Fixture file", handler: cmdValidateFixture },
668
+ {
669
+ name: "validate-suite",
670
+ usage: "<suite.json>",
671
+ summary: "Validate a Test Suite file (also checks DAG order/cycles)",
672
+ handler: cmdValidateSuite,
673
+ },
674
+ { name: "plan-suite", usage: "<suite.json>", summary: "Print a suite's resolved execution order", handler: cmdPlanSuite },
675
+ {
676
+ name: "validate-plan",
677
+ usage: "<plan.json>",
678
+ summary: "Validate a Test Plan file and every suite it references",
679
+ handler: cmdValidatePlan,
680
+ },
681
+ ],
682
+ },
683
+ {
684
+ title: "set up a project for LLM-driven replay",
685
+ commands: [
686
+ {
687
+ name: "init-skill",
688
+ usage: "[--force]",
689
+ summary: "Copy the replay-trxa-testplan skill into this project for Claude Code and Codex to pick up",
690
+ handler: cmdInitSkill,
691
+ },
692
+ ],
693
+ },
694
+ {
695
+ title: "run a suite or plan",
696
+ commands: [
697
+ {
698
+ name: "init-plan-run",
699
+ usage: "<plan.json> -o runs/",
700
+ summary: "Create a new PlanRun record for a plan, auto-generating its id",
701
+ handler: cmdInitPlanRun,
702
+ },
703
+ {
704
+ name: "init-run",
705
+ usage: "<suite.json> -o testruns/<suiteId>-<runId>.json",
706
+ summary: "Create a new Test Run file for a suite, all test cases pending",
707
+ handler: cmdInitRun,
708
+ },
709
+ {
710
+ name: "resolve-next",
711
+ usage: "<suite.json> <testrun.json> --testcases-dir <dir> [--fixtures-dir <dir>]",
712
+ summary: "Resolve the next runnable test case's inputs",
713
+ handler: cmdResolveNext,
714
+ },
715
+ {
716
+ name: "measure-tokens",
717
+ usage: "--since <isoTimestamp> --until <isoTimestamp> [--transcript <path>]",
718
+ summary: "Sum real token usage from Claude Code's own session log for a time window",
719
+ handler: cmdMeasureTokens,
720
+ },
721
+ {
722
+ name: "record-result",
723
+ usage: "<testrun.json> <testCaseId> --status passed|failed|blocked (--outputs '{...}' | --outputs-file <path>) " +
724
+ "[--assertions '[...]' | --assertions-file <path>]",
725
+ summary: "Record a test case's outcome into a Test Run",
726
+ handler: cmdRecordResult,
727
+ },
728
+ {
729
+ name: "plan-status",
730
+ usage: "<plan.json> <run.json> --testruns-dir <dir>",
731
+ summary: "Roll up a Test Plan's status across its suites' Test Runs for one PlanRun",
732
+ handler: cmdPlanStatus,
733
+ },
734
+ ],
735
+ },
736
+ {
737
+ title: "analyze a whole recordings library",
738
+ commands: [
739
+ {
740
+ name: "analyze-library",
741
+ usage: "<recordingsDir> [--report analysis/library-report.json] [--csv analysis/scrubbed-values.csv]",
742
+ summary: "Scan a directory of recordings; report structural coverage and gaps",
743
+ handler: cmdAnalyzeLibrary,
744
+ },
745
+ ],
746
+ },
747
+ {
748
+ title: "visual editor",
749
+ commands: [
750
+ { name: "studio", usage: "[stop]", summary: "Start (or stop) the Studio web UI", handler: cmdStudio },
751
+ ],
752
+ },
753
+ {
754
+ title: "back up & migrate a whole library",
755
+ commands: [
756
+ {
757
+ name: "export",
758
+ usage: "-o <backup.zip>",
759
+ summary: "Bundle recordings/testcases/testdata/testscripts/suites/plans/testruns into a zip",
760
+ handler: cmdExport,
761
+ },
762
+ {
763
+ name: "import",
764
+ usage: "<backup.zip> [--force]",
765
+ summary: "Unpack a library backup zip (refuses on name collisions unless --force)",
766
+ handler: cmdImport,
767
+ },
768
+ ],
769
+ },
770
+ ];
771
+ const COMMANDS = Object.fromEntries(COMMAND_GROUPS.flatMap((group) => group.commands).map((c) => [c.name, c]));
772
+ async function readPackageVersion(repoRoot) {
773
+ try {
774
+ const raw = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf-8"));
775
+ return raw.version ?? "0.0.0";
776
+ }
777
+ catch {
778
+ return "0.0.0";
779
+ }
780
+ }
781
+ function renderHelp(version) {
782
+ const nameCol = Math.max(...COMMAND_GROUPS.flatMap((g) => g.commands.map((c) => c.name.length)));
783
+ const groups = COMMAND_GROUPS.map((group) => {
784
+ const lines = group.commands.map((c) => ` ${c.name.padEnd(nameCol)} ${c.summary}`).join("\n");
785
+ return `${group.title}\n${lines}`;
786
+ }).join("\n\n");
787
+ return (`trxa-tool ${version} -- D365 Finance & Operations Task Recorder test automation\n\n` +
788
+ `Usage: trxa <command> [<args>]\n\n` +
789
+ `These are the trxa commands, grouped by what they're for:\n\n` +
790
+ `${groups}\n\n` +
791
+ `Run 'trxa <command>' with no further arguments to see that command's specific usage.`);
792
+ }
793
+ async function main() {
794
+ const [command, ...args] = process.argv.slice(2);
795
+ if (!command || command === "help" || command === "-h" || command === "--help") {
796
+ console.log(renderHelp(await readPackageVersion(REPO_ROOT)));
797
+ return;
798
+ }
799
+ if (command === "-v" || command === "--version") {
800
+ console.log(`trxa-tool ${await readPackageVersion(REPO_ROOT)}`);
801
+ return;
802
+ }
803
+ const spec = COMMANDS[command];
804
+ if (!spec) {
805
+ console.error(`trxa: '${command}' is not a trxa command. See 'trxa help' for the full list.`);
806
+ process.exitCode = 1;
807
+ return;
808
+ }
809
+ await spec.handler(args);
810
+ }
811
+ main().catch((err) => {
812
+ console.error(err);
813
+ process.exitCode = 1;
814
+ });