@aefree/pi-unity 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "exports": {
     ".": "./index.ts"
@@ -18,18 +18,18 @@
     ]
   },
   "scripts": {
-    "test": "tsx tests/unity-core.test.ts && tsx tests/unity-pipeline.test.ts && tsx tests/unity-processes.test.ts && tsx tests/pi-unity-settings.test.ts && tsx tests/unity-projects.test.ts && tsx tests/unity-guidance-audit.test.ts && tsx tests/unity-batchmode.test.ts && tsx tests/unity-test-batch.test.ts && tsx tests/unity-tests.test.ts && tsx tests/unity-cli.test.ts && tsx tests/unity-project-lock.test.ts && tsx tests/unity-artifact-profile.test.ts && tsx tests/unity-file-discovery-filter.test.ts && tsx tests/unity-registration.test.ts && tsx tests/unity-optional-integrations.test.ts && tsx tests/unity-package-validation.test.ts",
+    "test": "tsx tests/unity-core.test.ts && tsx tests/unity-launch.test.ts && tsx tests/unity-pipeline.test.ts && tsx tests/unity-processes.test.ts && tsx tests/pi-unity-settings.test.ts && tsx tests/unity-projects.test.ts && tsx tests/unity-guidance-audit.test.ts && tsx tests/unity-batchmode.test.ts && tsx tests/unity-test-batch.test.ts && tsx tests/unity-tests.test.ts && tsx tests/unity-cli.test.ts && tsx tests/unity-project-lock.test.ts && tsx tests/unity-artifact-profile.test.ts && tsx tests/unity-file-discovery-filter.test.ts && tsx tests/unity-registration.test.ts && tsx tests/unity-optional-integrations.test.ts && tsx tests/unity-package-validation.test.ts",
     "eval:guidance-skill": "tsx evals/auditing-unity-agent-guidance/run-eval.ts"
   },
   "dependencies": {
     "typebox": "1.3.8"
   },
   "peerDependencies": {
+    "@aefree/pi-file-discovery": "^0.1.0",
+    "@aefree/pi-project-artifacts": "^0.1.0",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "@aefree/pi-project-artifacts": "^0.1.0",
-    "@aefree/pi-file-discovery": "^0.1.0"
+    "@earendil-works/pi-tui": "*"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -48,11 +48,11 @@
   },
   "homepage": "https://github.com/aefreedman/pi-unity#readme",
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.83.0",
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@earendil-works/pi-tui": "0.83.0",
-    "@aefree/pi-project-artifacts": "^0.1.0",
     "@aefree/pi-file-discovery": "^0.1.0",
+    "@aefree/pi-project-artifacts": "^0.1.0",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "tsx": "^4.23.5"
   },
   "peerDependenciesMeta": {

package/skills/unity-batchmode-tests/SKILL.md

@@ -50,9 +50,9 @@ Use the `pi-unity` tools first instead of forming raw Unity CLI commands on the
 `unity_launch_batchmode` remains the default for custom agent-run headless Unity work because it already:
 - resolves the Unity project from a direct project root, a coordination root, or another nearby folder
 - reads `ProjectSettings/ProjectVersion.txt`
-- prefers the installed `unity run` CLI when available, falling back to OS-aware direct editor launch
+- treats installed `unity run` as authoritative when available: it receives the project path without `--editor-version` and reads the declared version itself, falling back only when Unity CLI is unavailable
 - uses OS-aware standard install probing
-- supports explicit `UNITY_EDITOR_PATH` / `unityEditorPath` overrides
+- resolves only exact project-version standard installation candidates when direct Editor fallback is required
 - strips direct-Editor flags managed by `unity run` (`-batchmode`, `-projectPath`, `-quit`) before forwarding args in Unity CLI mode
 - supports `launcher: "editor-executable"` when Unity CLI argument forwarding differs from direct Editor executable behavior
 - checks Unity CLI status and running Unity processes before launch
@@ -68,15 +68,15 @@ If a launch is blocked by a native Unity lockfile, call `unity_project_status` b
 
 ### 2. Get the Project's Unity Version
 
-If you are in direct CLI fallback mode, read `ProjectSettings/ProjectVersion.txt` in the Unity project root:
+Before direct Editor fallback, read `ProjectSettings/ProjectVersion.txt` in the Unity project root:
 
 ```
 m_EditorVersion: ####.#.#f#
 ```
 
-### 3. Find the Unity Executable
+### 3. Resolve the exact-version Unity Editor
 
-If you are in direct CLI fallback mode, check these locations based on platform and version:
+For direct Editor fallback, use only the standard locations constructed from the version declared in `ProjectVersion.txt`:
 
 **Windows:**
 ```
@@ -89,10 +89,9 @@ C:\UnityInstalls\<version>\Editor\Unity.exe
 ```
 /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity
 /Applications/Unity/<version>/Unity.app/Contents/MacOS/Unity
-/Applications/Unity*
 ```
 
-If not found, ask the user for their Unity install path.
+If the exact declared version is not found, do not use an arbitrary Editor path or a nearby version. Ask the user to install the declared version through their normal Unity installation workflow, or use Unity CLI after it can resolve that exact version.
 
 ### 4. Choose the execution route, then run tests
 
@@ -124,12 +123,13 @@ After choosing the isolated route:
 - exclude graphics-required screenshot/visual-capture tests from no-graphics runs
 - prefer project test categories such as `RequiresGraphics` / `VisualCapture` when the project exposes them
 
-Direct CLI fallback templates:
+Unity CLI project-authoritative template:
 ```
 unity test "<ProjectPath>" --mode <EditMode|PlayMode> --filter "<Full.Test.Name>" --output "<ResultsPath>" -- -logFile "<LogPath>"
-"<UnityEditorPath>" -batchmode -nographics -projectPath "<ProjectPath>" -runTests -testPlatform <EditMode|PlayMode> -testFilter "<Full.Test.Name>" -testResults "<ResultsPath>" -logFile "<LogPath>"
 ```
 
+For direct Editor fallback, use `unity_launch_batchmode` with its project path and test parameters; it resolves only the declared project's exact-version standard candidates.
+
 Fallback parameters:
 - `-testPlatform`: `EditMode` or `PlayMode`
 - `-testFilter`: Full test name (e.g., `MyNamespace.MyTests.TestMethodName`)

package/skills/unity-pipeline-workflows/SKILL.md

@@ -41,12 +41,30 @@ Call `unity_run_tests` with:
 
 The tool treats `no_tests`, idle, and not-started statuses as safe inactivity, detects a pre-existing active connected test before dispatch, and stops rather than claiming or replacing active work. It captures returned mode/filter/run identity fields when available and stops as uncertain if status is clearly displaced by another run.
 
+### Two independent fixtures in an open Editor
+
+Keep the Editor open. For an authorized request for two known non-overlapping fixtures, use the same explicit exact-copy `path` and platform, one selector per call. For example, replace `./SyntheticGame` with the selected project path and issue this `unity_run_tests` call:
+
+```json
+{"path":"./SyntheticGame","testPlatform":"EditMode","execution":"connected","testFilters":["Synthetic.InventoryFixture"]}
+```
+
+Await the completed tool result and inspect its outcome and exact normalized artifact path. Only after a passing result, issue the second call (not in parallel or pre-queued in the same turn):
+
+```json
+{"path":"./SyntheticGame","testPlatform":"EditMode","execution":"connected","testFilters":["Synthetic.DialogueFixture"]}
+```
+
+Stop the remaining sequence on failure, timeout, cancellation, malformed evidence, displaced identity, or any uncertainty; report the first result and the remaining fixture as not run. Do not retry, close the Editor, switch to isolated execution, or broaden to a parent suite/category or empty selectors. Empty/omitted selectors select all tests. Keep each result's artifact separately; do not treat one fixture's evidence as covering the other.
+
+For a single category use `testCategories: ["SyntheticCategory"]` and omit `testFilters`. Never combine the two families or join selectors with semicolons. Multiple-selector rejection means no test was dispatched: use the serial recipe only for independent, non-overlapping selections without other isolated-only requirements. If overlap or intended filter/category intersection semantics are unclear, stop for clarification rather than split, duplicate, or broaden tests. Required XML, retries, coverage, or other isolated-only options still need a deliberate isolation decision, not argument stripping.
+
 ## Bounded raw CLI troubleshooting only
 
 Normally call the typed tools, not raw CLI commands. If a typed tool is unavailable in an older installed package and a user specifically authorizes troubleshooting, first use `unity_project_status` and require advertised `recompile_status` or `run_tests` and `test_status`. Use the documented asynchronous form with `--async_tests true`, one fixed deadline, and bounded backoff; parse object and stringified nested JSON. `Total: 0` with `result: running` is a valid nonterminal initiating response. Passing evidence reports successful completion, a known positive executed-test count, and zero failures; nested `success:false`, changed exact-copy identity, or polling timeout is non-passing uncertainty. Do not silently fall back to batchmode after uncertain connected dispatch. Connected work does not guarantee NUnit XML.
 
 ## When not to use connected tools
 
-Use `unity_run_tests` with `execution: "isolated"` for a closed project, intentional isolation/CI, multiple selectors, retries, sharding, coverage, or required NUnit/JUnit evidence. A single category is supported connected when Pipeline advertises the command; do not claim broader connected selector support. Do not use batchmode as an automatic fallback after an uncertain connected dispatch.
+Use `unity_run_tests` with `execution: "isolated"` for a closed project, intentional isolation/CI, multiple selectors in one run, retries, sharding, coverage, or required NUnit/JUnit evidence. Multiple independent fixtures alone do not require closing a reachable Editor: use the serial recipe above. A single category is supported connected when Pipeline advertises the command; do not claim broader connected selector support. Do not use batchmode as an automatic fallback after an uncertain connected dispatch.
 
 Use the typed compile/test tools when their polling and terminal evidence fit the task. Advertised Pipeline `eval` remains available through `unity_pipeline_eval` for bounded project-specific inspection or operations outside those typed workflows; its `timeoutSeconds` range is 1–86,400 seconds, and a timeout remains uncertain without cancellation or retry. It is an assistance surface, not a forbidden fallback or a substitute for the typed tools' completion protocol. Eval compiles arbitrary C# with Roslyn on the Editor main thread, so ordinary properties and local-variable snippets are valid; it is not expression-only or reliably statically read-only. Prefer typed tools for their stronger evidence, but let user intent and project guidance govern mutations. Lifecycle, persistent-setting, destructive, asset, scene-save, package, build, and test mutations require explicit authorization.

package/src/unity-artifact-inspection.ts

@@ -0,0 +1,59 @@
+import { isAbsolute } from "node:path";
+import { determineUnityTestOutcome, type NormalizedUnityTestResult } from "./unity-tests";
+
+const outcomes = ["passed", "passed_with_flakes", "tests_failed", "empty_selection", "run_error", "timed_out", "cancelled", "uncertain"];
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const nonnegative = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+const count = (value: unknown): value is number => nonnegative(value) && Number.isSafeInteger(value);
+const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every(item => typeof item === "string" && !!item.trim() && !/[\0\r\n;]/.test(item));
+const relativeId = (value: unknown): value is string => typeof value === "string" && !!value.trim()
+  && !isAbsolute(value) && !/^(?:[A-Za-z]:|[\\/])/.test(value) && !value.split(/[\\/]/).includes("..") && !/\0/.test(value);
+
+/** Read the durable schema, not a transport response. Missing optional counts remain unknown.
+ * Test records may be bounded or absent: never require tests.length === summary.total.
+ */
+export function validateNormalizedUnityTestArtifact(value: unknown): NormalizedUnityTestResult {
+  const invalid = (reason: string): never => { throw new Error(`Invalid normalized Unity test artifact: ${reason}.`); };
+  if (!record(value) || value.schemaVersion !== 1) invalid("expected schemaVersion 1 object");
+  const result = value as Record<string, unknown>;
+  if (!["pipeline", "unity-cli", "editor-executable"].includes(result.source as string)) invalid("unsupported source");
+  if (!["EditMode", "PlayMode"].includes(result.platform as string)) invalid("unsupported platform");
+  if (!outcomes.includes(result.outcome as string)) invalid("unsupported outcome");
+  if (!record(result.selection) || !strings(result.selection.testFilters) || !strings(result.selection.testCategories)) invalid("selection must contain testFilters and testCategories arrays");
+  if (!record(result.summary)) invalid("summary must be an object");
+  const summary = result.summary as Record<string, unknown>;
+  for (const key of ["total", "passed", "failed", "skipped", "inconclusive"]) {
+    if (summary[key] !== undefined && !count(summary[key])) invalid(`summary.${key} must be a non-negative integer`);
+  }
+  if (count(summary.total)) {
+    const accounted = [summary.passed, summary.failed, summary.skipped, summary.inconclusive].reduce<number>((sum, item) => sum + (count(item) ? item : 0), 0);
+    if (accounted > summary.total) invalid("summary counts exceed total");
+  }
+  if (!Array.isArray(result.tests)) invalid("tests must be an array");
+  const tests = result.tests as unknown[];
+  for (const test of tests) {
+    if (!record(test) || typeof test.name !== "string" || !test.name.trim() || typeof test.status !== "string" || !test.status.trim()) invalid("test records require name and status");
+    const item = test as Record<string, unknown>;
+    for (const key of ["message", "stackTrace"]) if (item[key] !== undefined && typeof item[key] !== "string") invalid(`test ${key} must be a string`);
+    if (item.durationSeconds !== undefined && !nonnegative(item.durationSeconds)) invalid("test durationSeconds must be non-negative");
+    if (item.attempts !== undefined && (!count(item.attempts) || item.attempts < 1)) invalid("test attempts must be positive");
+  }
+  if (count(summary.total) && tests.length > summary.total) invalid("test records exceed total");
+  const typed = result as unknown as NormalizedUnityTestResult;
+  for (const [status, key] of [["passed", "passed"], ["failed", "failed"], ["skipped", "skipped"], ["inconclusive", "inconclusive"]] as const) {
+    const observed = typed.tests.filter(test => test.status.toLowerCase() === status).length;
+    if (count(summary[key]) && observed > summary[key]) invalid(`test records conflict with summary.${key}`);
+  }
+  if (result.projectRelativeId !== undefined && !relativeId(result.projectRelativeId)) invalid("projectRelativeId must be project-relative");
+  if (result.backendArtifacts !== undefined && (!record(result.backendArtifacts) || !Object.values(result.backendArtifacts).every(relativeId))) invalid("backendArtifacts must contain project-relative paths");
+  for (const key of ["startedAt", "completedAt"]) if (result[key] !== undefined && (typeof result[key] !== "string" || !Number.isFinite(Date.parse(result[key] as string)))) invalid(`${key} must be a timestamp`);
+  if (typed.startedAt && typed.completedAt && Date.parse(typed.completedAt) < Date.parse(typed.startedAt)) invalid("completion precedes start");
+  if (result.durationSeconds !== undefined && !nonnegative(result.durationSeconds)) invalid("durationSeconds must be non-negative");
+  if (result.flakyTests !== undefined && (!Array.isArray(result.flakyTests) || !result.flakyTests.every(item => record(item) && typeof item.name === "string" && !!item.name.trim() && count(item.attempts) && item.attempts > 0))) invalid("invalid flakyTests");
+  if (result.outcome === "passed" || result.outcome === "passed_with_flakes") {
+    if (determineUnityTestOutcome(typed.summary) !== "passed" || typed.tests.some(test => !["passed", "success"].includes(test.status.toLowerCase()))) invalid("passing outcome lacks consistent positive passing counts/records");
+    if (result.outcome === "passed_with_flakes" && !typed.flakyTests?.length) invalid("passed_with_flakes requires flakyTests evidence");
+  }
+  if (result.outcome === "empty_selection" && ((typed.summary.total ?? 0) > 0 || tests.length > 0)) invalid("empty selection conflicts with executed tests");
+  return typed;
+}

package/src/unity-batchmode.ts

@@ -29,6 +29,8 @@ export type UnityParsedTestResults = {
   failedTests: UnityFailedTest[];
   /** Complete bounded per-test evidence for normalized artifacts, never routine tool output. */
   tests: UnityParsedTestCase[];
+  /** Observed XML record lower bounds, counted before record output is truncated. */
+  testRecordCounts?: { total: number; passed: number; failed: number; skipped: number; inconclusive: number; other: number };
 };
 
 export type UnityBatchmodeArtifacts = {
@@ -82,10 +84,10 @@ function decodeXmlText(value: string | undefined): string | undefined {
 
 function parseAttributes(tagSource: string): Record<string, string> {
   const attributes: Record<string, string> = {};
-  const attributeRegex = /(\w[\w:-]*)\s*=\s*"([^"]*)"/g;
+  const attributeRegex = /(\w[\w:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
   for (const match of tagSource.matchAll(attributeRegex)) {
     const key = match[1];
-    const value = match[2] ?? "";
+    const value = match[2] ?? match[3] ?? "";
     attributes[key] = value;
   }
   return attributes;
@@ -102,6 +104,12 @@ function parseOptionalNumber(value: string | undefined): number | undefined {
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
+function parseTestCount(value: string | undefined): number | undefined {
+  // Only omission is unknown. Retain invalid supplied counters as NaN so the
+  // inspection validator rejects them instead of silently treating them as absent.
+  return value === undefined ? undefined : value.trim() ? Number(value) : Number.NaN;
+}
+
 export function parseUnityTestResultsXml(xml: string): UnityParsedTestResults | null {
   const testRunMatch = xml.match(/<test-run\b([^>]*)>/i);
   const testRunCloseIndex = xml.search(/<\/test-run\s*>/i);
@@ -112,33 +120,43 @@ export function parseUnityTestResultsXml(xml: string): UnityParsedTestResults |
   const rootAttributes = parseAttributes(testRunMatch[1] ?? "");
   const failedTests: UnityFailedTest[] = [];
   const tests: UnityParsedTestCase[] = [];
+  const testRecordCounts = { total: 0, passed: 0, failed: 0, skipped: 0, inconclusive: 0, other: 0 };
 
-  const testCaseRegex = /<test-case\b([^>]*)>([\s\S]*?)<\/test-case>/gi;
+  // Match the self-closing alternative first so it cannot consume the body of
+  // the next paired record. Both forms carry authoritative failure evidence.
+  const testCaseRegex = /<test-case\b([^>]*?)(?:\/\s*>|>([\s\S]*?)<\/test-case\s*>)/gi;
   for (const match of xml.matchAll(testCaseRegex)) {
     const attributes = parseAttributes(match[1] ?? "");
     const body = match[2] ?? "";
     const result = String(attributes.result ?? attributes.label ?? "").toLowerCase();
     const success = String(attributes.success ?? "").toLowerCase();
     const isFailure = result === "failed" || success === "false";
+    const status = isFailure ? "Failed" : attributes.result ?? attributes.label ?? "Unknown";
+    const statusKey = isFailure ? "failed" : result === "passed" || result === "success" ? "passed" : result === "skipped" ? "skipped" : result === "inconclusive" ? "inconclusive" : "other";
+    testRecordCounts.total++;
+    testRecordCounts[statusKey]++;
     const failureMessage = body.match(/<message[^>]*>([\s\S]*?)<\/message>/i);
     const stackTrace = body.match(/<stack-trace[^>]*>([\s\S]*?)<\/stack-trace>/i);
     const name = truncateEvidence(attributes.fullname ?? attributes.name ?? "(unknown test)", 1_000) ?? "(unknown test)";
-    if (tests.length < 2_000) tests.push({ name, status: attributes.result ?? attributes.label ?? "Unknown", ...(parseOptionalNumber(attributes.duration) === undefined ? {} : { durationSeconds: parseOptionalNumber(attributes.duration) }), ...(truncateEvidence(decodeXmlText(failureMessage?.[1]), 4_000) ? { message: truncateEvidence(decodeXmlText(failureMessage?.[1]), 4_000) } : {}), ...(truncateEvidence(decodeXmlText(stackTrace?.[1]), 8_000) ? { stackTrace: truncateEvidence(decodeXmlText(stackTrace?.[1]), 8_000) } : {}) });
+    if (tests.length < 2_000) tests.push({ name, status, ...(parseOptionalNumber(attributes.duration) === undefined ? {} : { durationSeconds: parseOptionalNumber(attributes.duration) }), ...(truncateEvidence(decodeXmlText(failureMessage?.[1]), 4_000) ? { message: truncateEvidence(decodeXmlText(failureMessage?.[1]), 4_000) } : {}), ...(truncateEvidence(decodeXmlText(stackTrace?.[1]), 8_000) ? { stackTrace: truncateEvidence(decodeXmlText(stackTrace?.[1]), 8_000) } : {}) });
     if (!isFailure) continue;
     if (failedTests.length < 50) failedTests.push({ name, message: truncateEvidence(decodeXmlText(failureMessage?.[1]), 1_000), stackTrace: truncateEvidence(decodeXmlText(stackTrace?.[1]), 4_000) });
   }
 
-  const skipped = parseOptionalNumber(rootAttributes.skipped) ?? parseOptionalNumber(rootAttributes.inconclusive);
+  // These are separate counters. Synthesizing skipped from inconclusive makes
+  // combined-count validation double-count one observed category.
+  const skipped = parseTestCount(rootAttributes.skipped);
 
   const parsed: UnityParsedTestResults = {
-    total: parseOptionalNumber(rootAttributes.total) ?? parseOptionalNumber(rootAttributes.testcasecount),
-    passed: parseOptionalNumber(rootAttributes.passed),
-    failed: parseOptionalNumber(rootAttributes.failed),
+    total: parseTestCount(rootAttributes.total) ?? parseTestCount(rootAttributes.testcasecount),
+    passed: parseTestCount(rootAttributes.passed),
+    failed: parseTestCount(rootAttributes.failed),
     skipped,
-    inconclusive: parseOptionalNumber(rootAttributes.inconclusive),
+    inconclusive: parseTestCount(rootAttributes.inconclusive),
     durationSeconds: parseOptionalNumber(rootAttributes.duration),
     failedTests,
     tests,
+    testRecordCounts,
   };
   if (parsed.total === undefined && parsed.passed === undefined && parsed.failed === undefined && parsed.failedTests.length === 0) {
     return null;
@@ -146,6 +164,23 @@ export function parseUnityTestResultsXml(xml: string): UnityParsedTestResults |
   return parsed;
 }
 
+/** Missing counters and omitted/bounded records are unknown, not zero executions.
+ * Supplied counters and observed record lower bounds must nevertheless agree.
+ * An optional linked summary can fill missing XML counters, not replace them.
+ */
+export function hasConflictingUnityXmlTestEvidence(
+  results: UnityParsedTestResults,
+  linkedSummary?: Pick<UnityParsedTestResults, "total" | "passed" | "failed" | "skipped" | "inconclusive">,
+): boolean {
+  const keys = ["total", "passed", "failed", "skipped", "inconclusive"] as const;
+  const counts = Object.fromEntries(keys.map(key => [key, results[key] ?? linkedSummary?.[key]])) as Pick<UnityParsedTestResults, typeof keys[number]>;
+  if (keys.some(key => counts[key] !== undefined && (!Number.isSafeInteger(counts[key]) || counts[key]! < 0))) return true;
+  const observed = results.testRecordCounts;
+  if (keys.some(key => counts[key] !== undefined && (observed?.[key] ?? 0) > counts[key]!)) return true;
+  const accounted = keys.slice(1).reduce((sum, key) => sum + Math.max(counts[key] ?? 0, observed?.[key] ?? 0), 0);
+  return counts.total !== undefined && accounted > counts.total;
+}
+
 function buildArtifactCandidates(cwd: string, projectRoot: string, rawPath: string): string[] {
   if (path.isAbsolute(rawPath)) {
     return [path.normalize(rawPath)];

package/src/unity-cli.ts

@@ -13,8 +13,7 @@ export type UnityCliCommand = {
 };
 
 export type UnityCliLaunchOptions = {
-  editorVersion?: string;
-  editorPath?: string;
+  editorVersionOverride?: string;
   timeoutSeconds?: number;
   cliCommand?: string;
   useGraphics?: boolean;
@@ -84,11 +83,8 @@ function unityCliBaseArgs(): string[] {
 }
 
 function appendUnityCliEditorOptions(args: string[], options: UnityCliLaunchOptions): void {
-  if (options.editorVersion?.trim()) {
-    args.push("--editor-version", options.editorVersion.trim());
-  }
-  if (options.editorPath?.trim()) {
-    args.push("--editor-path", options.editorPath.trim());
+  if (options.editorVersionOverride?.trim()) {
+    args.push("--editor-version", options.editorVersionOverride.trim());
   }
 }
 
@@ -651,11 +647,11 @@ export async function dispatchUnityPlanningInspection(
     ...(isEval ? [request.evalSnippet!.trim()] : request.args ?? []),
   ];
   const execution = await options.execute(command, args, { timeout: options.timeout ?? UNITY_CLI_DISCOVERY_TIMEOUT_MS, signal: options.signal });
+  const raw = [execution.stdout, execution.stderr].filter(Boolean).join("\n");
+  const output = summarizeUnityCliText(redactUnityPlanningOutput(raw), 4_000, 40);
   if (execution.error) {
-    return { outcome: "rejected", code: isUnityCliTimeout(execution) ? "planning_command_timeout" : "planning_command_failed", message: "Connected command did not complete successfully; its effect may be uncertain." };
+    return { outcome: "rejected", code: isUnityCliTimeout(execution) ? "planning_command_timeout" : "planning_command_failed", message: `Connected command did not complete successfully; its effect may be uncertain.${output ? ` ${output}` : ""}` };
   }
-  const raw = [execution.stdout, execution.stderr].filter(Boolean).join("\n");
-  const output = redactUnityPlanningOutput(summarizeUnityCliText(raw, 4_000, 40));
   const reportedFailure = connectedCommandFailure(execution.stdout, isEval);
   if (reportedFailure) {
     return {

package/src/unity-core.ts

@@ -27,14 +27,6 @@ export function parseUnityVersionText(contents: string): string | null {
   return match ? match[1] : null;
 }
 
-export function normalizeUnityEditorOverride(editorPath: string, platform: SupportedPlatform): string {
-  const normalized = path.normalize(editorPath.trim());
-  if (platform === "darwin" && normalized.toLowerCase().endsWith(".app")) {
-    return path.join(normalized, "Contents", "MacOS", "Unity");
-  }
-  return normalized;
-}
-
 export function buildUnityEditorCandidates(
   version: string,
   platform: SupportedPlatform = process.platform,
@@ -112,8 +104,8 @@ export function normalizeForCommandSearch(value: string, platform: SupportedPlat
   return platform === "win32" ? normalized.toLowerCase() : normalized;
 }
 
-function realpathMatchesOnDarwin(candidatePath: string, projectRoot: string, platform: SupportedPlatform): boolean | null {
-  if (platform !== "darwin" || process.platform !== "darwin") {
+function realpathMatchesOnNativePlatform(candidatePath: string, projectRoot: string, platform: SupportedPlatform): boolean | null {
+  if ((platform !== "darwin" && platform !== "win32") || process.platform !== platform) {
     return null;
   }
 
@@ -121,7 +113,7 @@ function realpathMatchesOnDarwin(candidatePath: string, projectRoot: string, pla
     return realpathSync.native(candidatePath) === realpathSync.native(projectRoot);
   } catch {
     // Only use filesystem identity when both paths can be resolved. Falling back
-    // to the case-sensitive textual comparison preserves case-sensitive APFS.
+    // to the platform-specific textual comparison preserves existing behavior.
     return null;
   }
 }
@@ -138,7 +130,7 @@ export function projectPathsMatch(candidatePath: string, projectRoot: string, pl
     return false;
   }
 
-  const realpathMatch = realpathMatchesOnDarwin(trimmedCandidatePath, trimmedProjectRoot, comparisonPlatform);
+  const realpathMatch = realpathMatchesOnNativePlatform(trimmedCandidatePath, trimmedProjectRoot, comparisonPlatform);
   if (realpathMatch !== null) {
     return realpathMatch;
   }

package/src/unity-editor-fallback.ts

@@ -0,0 +1,36 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+  buildUnityBatchmodeArgs,
+  buildUnityEditorCandidates,
+  buildUnityOpenEditorArgs,
+  type SupportedPlatform,
+  type UnityOpenEditorArgsOptions,
+} from "./unity-core";
+
+/** Direct-executable compatibility fallback. Unity CLI routes must not import this module. */
+export async function resolveUnityEditorPath(
+  unityVersion: string,
+  options: { platform?: SupportedPlatform; homeDir?: string; access?: (candidate: string) => Promise<void> } = {},
+): Promise<string> {
+  const autoCandidates = buildUnityEditorCandidates(unityVersion, options.platform ?? process.platform, options.homeDir);
+  const access = options.access ?? ((candidate: string) => fs.access(candidate, fs.constants.X_OK));
+  for (const candidate of autoCandidates) {
+    try { await access(candidate); return path.normalize(candidate); } catch { /* Try next exact-version candidate. */ }
+  }
+  throw new Error(`Could not find a Unity Editor executable for Unity ${unityVersion}. Install that exact Editor version through your normal Unity installation workflow, or install Unity CLI so it can resolve the project version.`);
+}
+
+export function launchUnityEditorDetached(editorPath: string, projectRoot: string, options: UnityOpenEditorArgsOptions = {}): { pid: number | undefined; args: string[]; command: string } {
+  const args = buildUnityOpenEditorArgs(projectRoot, options);
+  const child = (awaitableSpawn)(editorPath, args, { detached: true, stdio: "ignore", windowsHide: false });
+  child.unref();
+  return { pid: child.pid, args, command: editorPath };
+}
+
+// Kept local so this module owns direct process creation entirely.
+import { spawn as awaitableSpawn } from "node:child_process";
+
+export function createUnityBatchmodeCommand(editorPath: string, projectRoot: string, extraArgs: string[] = [], options: { useGraphics?: boolean } = {}): { command: string; args: string[] } {
+  return { command: editorPath, args: buildUnityBatchmodeArgs(projectRoot, extraArgs, options) };
+}

package/src/unity-launch.ts

@@ -1,90 +1,10 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
 import { spawn } from "node:child_process";
-import {
-  buildUnityBatchmodeArgs,
-  buildUnityEditorCandidates,
-  buildUnityOpenEditorArgs,
-  normalizeUnityEditorOverride,
-  type SupportedPlatform,
-  type UnityOpenEditorArgsOptions,
-} from "./unity-core";
 import { createUnityCliOpenCommand, type UnityCliLaunchOptions } from "./unity-cli";
 
-export async function resolveUnityEditorPath(
-  unityVersion: string,
-  options: {
-    overridePath?: string;
-    env?: NodeJS.ProcessEnv;
-    platform?: SupportedPlatform;
-    homeDir?: string;
-  } = {},
-): Promise<string> {
-  const platform = options.platform ?? process.platform;
-  const env = options.env ?? process.env;
-  const homeDir = options.homeDir;
-
-  const overrideCandidates = [options.overridePath, env.UNITY_EDITOR_PATH, env.UNITY_PATH]
-    .map((value) => value?.trim())
-    .filter((value): value is string => Boolean(value))
-    .map((value) => normalizeUnityEditorOverride(value, platform));
-
-  const autoCandidates = buildUnityEditorCandidates(unityVersion, platform, homeDir);
-
-  for (const candidate of [...overrideCandidates, ...autoCandidates]) {
-    try {
-      await fs.access(candidate, fs.constants.X_OK);
-      return path.normalize(candidate);
-    } catch {
-      // Try next candidate.
-    }
-  }
-
-  throw new Error(
-    [
-      `Could not find a Unity Editor executable for Unity ${unityVersion}.`,
-      "Set UNITY_EDITOR_PATH to an explicit executable path or pass unityEditorPath.",
-    ].join(" "),
-  );
-}
-
-export function launchUnityEditorDetached(
-  editorPath: string,
-  projectRoot: string,
-  options: UnityOpenEditorArgsOptions = {},
-): { pid: number | undefined; args: string[]; command: string } {
-  const args = buildUnityOpenEditorArgs(projectRoot, options);
-  const child = spawn(editorPath, args, {
-    detached: true,
-    stdio: "ignore",
-    windowsHide: false,
-  });
-  child.unref();
-  return { pid: child.pid, args, command: editorPath };
-}
-
-export function launchUnityCliOpenDetached(
-  projectRoot: string,
-  options: UnityCliLaunchOptions = {},
-): { pid: number | undefined; args: string[]; command: string } {
+/** Unity CLI GUI launch path. Direct executable fallback lives in unity-editor-fallback.ts. */
+export function launchUnityCliOpenDetached(projectRoot: string, options: UnityCliLaunchOptions = {}): { pid: number | undefined; args: string[]; command: string } {
   const cli = createUnityCliOpenCommand(projectRoot, options);
-  const child = spawn(cli.command, cli.args, {
-    detached: true,
-    stdio: "ignore",
-    windowsHide: false,
-  });
+  const child = spawn(cli.command, cli.args, { detached: true, stdio: "ignore", windowsHide: false });
   child.unref();
   return { pid: child.pid, args: cli.args, command: cli.command };
 }
-
-export function createUnityBatchmodeCommand(
-  editorPath: string,
-  projectRoot: string,
-  extraArgs: string[] = [],
-  options: { useGraphics?: boolean } = {},
-): { command: string; args: string[] } {
-  return {
-    command: editorPath,
-    args: buildUnityBatchmodeArgs(projectRoot, extraArgs, options),
-  };
-}

package/src/unity-projects.ts

@@ -5,7 +5,8 @@ import { parseUnityVersionText, resolveAbsolutePath } from "./unity-core";
 export type UnityProjectCandidate = {
   projectRoot: string;
   projectName: string;
-  unityVersion: string;
+  /** Manual ProjectVersion.txt evidence, loaded only by direct/Pipeline routes. */
+  unityVersion?: string;
 };
 
 export type UnityProjectDiscoveryResult = {
@@ -81,7 +82,6 @@ export async function findAncestorUnityProject(startDir: string): Promise<UnityP
       return {
         projectRoot: current,
         projectName: path.basename(current),
-        unityVersion: await readUnityVersion(current),
       };
     }
 
@@ -123,7 +123,6 @@ export async function discoverUnityProjects(
       candidates.push({
         projectRoot: next.dir,
         projectName: path.basename(next.dir),
-        unityVersion: await readUnityVersion(next.dir),
       });
       if (candidates.length >= maxCandidates) {
         truncated = true;

package/src/unity-tests.ts

@@ -63,6 +63,19 @@ export type NormalizedUnityTestResult = {
 };
 
 export type UnityTestRouteRequirements = { requiresIsolation: boolean; reasons: string[] };
+
+export function resolveUnityCliBackendReportPaths(
+  paths: { nunit: string; junit: string; log: string },
+  formats: UnityTestReportFormat[],
+): { nunit: string; junit?: string; log: string } {
+  // Normalized JSON is derived from Unity CLI's native NUnit XML, so the
+  // backend report is required even when callers do not retain NUnit output.
+  return {
+    nunit: paths.nunit,
+    junit: formats.includes("junit") ? paths.junit : undefined,
+    log: paths.log,
+  };
+}
 export type UnityTestOutcomeEvidence = {
   cancelled?: boolean;
   timedOut?: boolean;