@aeonsparx/pi-unreal 0.0.0-stage → 1.1.0

package/extensions/unreal/lib/plugin-resolver.ts

@@ -0,0 +1,305 @@
+/**
+ * Plugin discovery and reference resolution.
+ *
+ * Discovery order mirrors `UnrealBuildTool.System.ReadAvailablePlugins()`
+ * (`Engine/Source/Programs/UnrealBuildTool/System/Plugins.cs:322`):
+ *   1. Engine plugins      — `<EngineRoot>/Engine/Plugins`                     (`EPluginType::Engine`)
+ *   2. Project plugins     — `<ProjectDir>/Plugins`                            (`EPluginType::Project`)
+ *   3. Mods              — `<ProjectDir>/Mods`                               (`EPluginType::Mod`)
+ *   4. Additional dirs     — `.uproject` `AdditionalPluginDirectories`         (`EPluginType::External`)
+ * Later scans win on a name collision: a project plugin shadows an engine plugin of the same
+ * name, which is exactly what a marketplace copy of an engine plugin does.
+ *
+ * Reference semantics mirror `PluginManager` (`Engine/Source/Runtime/Projects/Private/…`):
+ * a `.uproject` reference is `Enabled` / `Optional` / `Activate` (`PluginReferenceDescriptor.cpp:132-172`),
+ * and an engine-version mismatch is a warning, not an error (`FEngineVersion::Parse` +
+ * `GetNewest`, `PluginManager.cpp:2690-2712`).
+ */
+
+import { parseUplugin, versionToMajorMinor, type EngineVersion, type PluginReference, type UprojectDescriptor, type UpluginDescriptor } from "./descriptors.ts";
+import { joinPath, normalizePath, realFs, shortHash, type FsAdapter } from "./util.ts";
+
+export type PluginSource = "Engine" | "Project" | "Mod" | "External";
+
+const SOURCE_RANK: Record<PluginSource, number> = { Engine: 1, Project: 2, Mod: 3, External: 4 };
+
+/**
+ * Bucket order for one plugin name: the copy the engine actually loads comes first
+ * (Engine < Project < Mod < External), ties broken by path. Shared with the cache layer so a
+ * cache hit cannot return a different shadow winner than a cold scan.
+ */
+export function comparePluginSource(a: { source: PluginSource; path: string }, b: { source: PluginSource; path: string }): number {
+	return SOURCE_RANK[b.source] - SOURCE_RANK[a.source] || a.path.localeCompare(b.path);
+}
+
+/** Cached, compact view of a `.uplugin`. Full descriptor is re-parsed on demand from disk. */
+export interface PluginSummary {
+	name: string;
+	path: string;
+	dir: string;
+	source: PluginSource;
+	version?: string;
+	semVersion?: string;
+	versionName?: string;
+	engineVersionRaw?: string;
+	category?: string;
+	friendlyName?: string;
+	description?: string;
+	enabledByDefault: boolean;
+	canContainContent: boolean;
+	isBetaVersion: boolean;
+	installed: boolean;
+	supportedTargetPlatforms: string[];
+	modules: { moduleName: string; type?: string; loadingPhase?: string }[];
+	plugins: { name: string; enabled: boolean; optional: boolean; activate: boolean }[];
+	diagnostics: string[];
+}
+
+export interface PluginIndex {
+	engineRoot?: string;
+	projectDir?: string;
+	additionalDirs: string[];
+	scannedDirs: string[];
+	scannedFiles: number;
+	entries: PluginSummary[];
+	byName: Map<string, PluginSummary[]>;
+	builtAtMs: number;
+}
+
+export interface BuildPluginIndexOptions {
+	engineRoot?: string;
+	projectDir?: string;
+	additionalPluginDirectories?: string[];
+	/** Extra roots treated as Project-type plugins (`.uproject` AdditionalRootDirectories). */
+	additionalRootDirectories?: string[];
+	fs?: FsAdapter;
+	now?: () => number;
+}
+
+/**
+ * Scan roots in discovery order. Exported so the cache key and the builder agree on exactly
+ * which directories an index covers.
+ */
+export function computeScanDirs(options: BuildPluginIndexOptions): { dir: string; source: PluginSource }[] {
+	const specs: { dir: string; source: PluginSource }[] = [];
+	if (options.engineRoot) specs.push({ dir: joinPath(normalizePath(options.engineRoot), "Engine/Plugins"), source: "Engine" });
+	if (options.projectDir) {
+		specs.push({ dir: joinPath(normalizePath(options.projectDir), "Plugins"), source: "Project" });
+		specs.push({ dir: joinPath(normalizePath(options.projectDir), "Mods"), source: "Mod" });
+	}
+	for (const dir of options.additionalPluginDirectories ?? []) {
+		const resolved = normalizePath(dir);
+		specs.push({ dir: options.projectDir && dir.startsWith(".") ? joinPath(normalizePath(options.projectDir), dir) : resolved, source: "External" });
+	}
+	for (const dir of options.additionalRootDirectories ?? []) {
+		specs.push({ dir: joinPath(normalizePath(dir), "Plugins"), source: "External" });
+	}
+	return specs;
+}
+
+async function scanUplugins(dir: string, source: PluginSource, fs: FsAdapter): Promise<PluginSummary[]> {
+	// fast-glob is imported lazily: an index rebuild is the only caller that needs it.
+	const { default: fastGlob } = await import("fast-glob");
+	let found: string[] = [];
+	try {
+		found = await fastGlob(["**/*.uplugin"], {
+			cwd: dir,
+			absolute: true,
+			dot: false,
+			followSymbolicLinks: false,
+			ignore: ["**/Binaries/**", "**/Intermediate/**", "**/Saved/**", "**/.git/**", "**/ThirdParty/**"],
+		});
+	} catch {
+		return [];
+	}
+	const out: PluginSummary[] = [];
+	for (const raw of found) {
+		const path = normalizePath(raw);
+		if (!fs.exists(path)) continue;
+		out.push(toSummary(parseUplugin(path, fs), source));
+	}
+	return out;
+}
+
+export function toSummary(descriptor: UpluginDescriptor, source: PluginSource): PluginSummary {
+	return {
+		name: descriptor.name,
+		path: descriptor.path,
+		dir: descriptor.path.slice(0, descriptor.path.lastIndexOf("/")),
+		source,
+		version: descriptor.version,
+		semVersion: descriptor.semVersion,
+		versionName: descriptor.versionName,
+		engineVersionRaw: descriptor.engineVersion?.raw,
+		category: descriptor.category,
+		friendlyName: descriptor.friendlyName,
+		description: descriptor.description,
+		enabledByDefault: descriptor.enabledByDefault,
+		canContainContent: descriptor.canContainContent,
+		isBetaVersion: descriptor.isBetaVersion,
+		installed: descriptor.installed,
+		supportedTargetPlatforms: descriptor.supportedTargetPlatforms,
+		modules: descriptor.modules.map((entry) => ({
+			moduleName: entry.moduleName,
+			type: entry.descriptor.type,
+			loadingPhase: entry.descriptor.loadingPhase,
+		})),
+		plugins: descriptor.plugins.map((ref) => ({ name: ref.name, enabled: ref.enabled, optional: ref.optional, activate: ref.activate })),
+		diagnostics: descriptor.diagnostics,
+	};
+}
+
+/**
+ * Build the plugin index for one project.
+ *
+ * Cold cost on a real install is the engine scan (UE 5.8: 897 `.uplugin` files). The result is
+ * cached on disk by `cache.ts`, keyed on engine version + directory mtimes.
+ */
+export async function buildPluginIndex(options: BuildPluginIndexOptions): Promise<PluginIndex> {
+	const fs = options.fs ?? realFs;
+	const now = options.now ?? (() => Date.now());
+	const scanSpecs = computeScanDirs(options);
+
+	const entries: PluginSummary[] = [];
+	const scannedDirs: string[] = [];
+	for (const spec of scanSpecs) {
+		if (!fs.isDirectory(spec.dir)) continue;
+		scannedDirs.push(spec.dir);
+		entries.push(...(await scanUplugins(spec.dir, spec.source, fs)));
+	}
+
+	const byName = new Map<string, PluginSummary[]>();
+	for (const entry of entries) {
+		const key = entry.name.toLowerCase();
+		const bucket = byName.get(key);
+		if (bucket) bucket.push(entry);
+		else byName.set(key, [entry]);
+	}
+	for (const bucket of byName.values()) {
+		bucket.sort(comparePluginSource);
+	}
+
+	return {
+		engineRoot: options.engineRoot ? normalizePath(options.engineRoot) : undefined,
+		projectDir: options.projectDir ? normalizePath(options.projectDir) : undefined,
+		additionalDirs: (options.additionalPluginDirectories ?? []).map(normalizePath),
+		scannedDirs,
+		scannedFiles: entries.length,
+		entries,
+		byName,
+		builtAtMs: now(),
+	};
+}
+
+export interface PluginReferenceResult {
+	name: string;
+	status: "resolved" | "disabled" | "missing" | "version-warning" | "shadowed" | "no-modules" | "beta";
+	/** Winning plugin, when the name resolves. */
+	plugin?: PluginSummary;
+	/** Same-name entries the winner displaced (`shadowed` lists them for transparency). */
+	shadowed: PluginSummary[];
+	/** Engine-version note mirroring `PluginManager`'s warning; absent when compatible. */
+	versionNote?: string;
+	notes: string[];
+}
+
+/** Resolve every `Plugins` entry of a `.uproject` against the index. */
+export function resolveProjectPlugins(
+	descriptor: UprojectDescriptor,
+	index: PluginIndex,
+	engineVersion: EngineVersion | undefined,
+	options: { targetPlatform?: string } = {},
+): PluginReferenceResult[] {
+	const out: PluginReferenceResult[] = [];
+	for (const ref of descriptor.plugins) {
+		out.push(resolvePluginReference(ref, index, engineVersion, options));
+	}
+	return out;
+}
+
+export function resolvePluginReference(
+	ref: PluginReference,
+	index: PluginIndex,
+	engineVersion: EngineVersion | undefined,
+	options: { targetPlatform?: string } = {},
+): PluginReferenceResult {
+	const bucket = index.byName.get(ref.name.toLowerCase()) ?? [];
+	const base = { name: ref.name, shadowed: bucket.slice(1), notes: [] as string[] } as PluginReferenceResult;
+
+	if (ref.supportedTargetPlatforms.length > 0 && options.targetPlatform && !ref.supportedTargetPlatforms.includes(options.targetPlatform)) {
+		base.notes.push(`reference lists SupportedTargetPlatforms [${ref.supportedTargetPlatforms.join(", ")}], not ${options.targetPlatform}`);
+	}
+	if (!ref.enabled) {
+		base.status = "disabled";
+		base.plugin = bucket[0];
+		base.notes.push("Enabled: false in the .uproject reference");
+		return base;
+	}
+	const winner = bucket[0];
+	if (!winner) {
+		base.status = "missing";
+		base.notes.push(
+			`no .uplugin named ${ref.name} under ${index.scannedDirs.join(" | ") || "(no plugin directories found)"}${ref.optional ? "; reference is Optional so the build tolerates it" : ""}`,
+		);
+		return base;
+	}
+	base.plugin = winner;
+	if (bucket.length > 1) {
+		base.notes.push(
+			`${winner.source} ${winner.name} shadows ${bucket
+				.slice(1)
+				.map((entry) => `${entry.source} ${entry.name}`)
+				.join(", ")} — the engine loads the first match found (Engine < Project < Mod < External)`,
+		);
+	}
+	if (winner.modules.length === 0) base.notes.push("plugin declares no modules");
+	if (winner.isBetaVersion) base.notes.push("IsBetaVersion: true (metadata only in UE 5.8: read at PluginDescriptor.cpp:371 and PluginDescriptor.cs:397, no engine/UBT beta gate found)");
+	/* Engine truth: `.uplugin` has no `Enabled` key (PluginDescriptor.cpp never reads it). Default
+	   enablement is `EnabledByDefault` -> FPlugin::IsEnabledByDefault (PluginManager.cpp:421-431),
+	   and a `"Enabled": true` reference is what loads a plugin that is not enabled by default — so a
+	   plugin's own flag is information, never a warning. */
+	if (ref.enabled && winner.enabledByDefault && !ref.activate) {
+		base.notes.push("plugin is EnabledByDefault: true, so it loads even without this reference");
+	}
+
+	const versionNote = comparePluginEngineVersion(winner, engineVersion);
+	if (versionNote) base.notes.push(versionNote);
+
+	let status: PluginReferenceResult["status"] = "resolved";
+	if (winner.modules.length === 0) status = "no-modules";
+	else if (winner.isBetaVersion) status = "beta";
+	if (versionNote) status = "version-warning";
+	base.status = status;
+	if (versionNote) base.versionNote = versionNote;
+	return base;
+}
+
+/** Mirrors `PluginManager.cpp:2690-2712`: mismatch is a warning naming both sides. */
+function comparePluginEngineVersion(plugin: PluginSummary, engineVersion: EngineVersion | undefined): string | undefined {
+	if (!plugin.engineVersionRaw || !engineVersion) return undefined;
+	const declared = versionToMajorMinor(parseEngineVersionRaw(plugin.engineVersionRaw));
+	const current = versionToMajorMinor(engineVersion);
+	if (!declared || !current) return undefined;
+	if (declared === current) return undefined;
+	return `plugin EngineVersion ${plugin.engineVersionRaw} differs from engine ${engineVersion.raw} (PluginManager warns on load)`;
+}
+
+function parseEngineVersionRaw(raw: string): EngineVersion | undefined {
+	const match = raw.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-(\d+))?(?:\+(.*))?$/);
+	if (!match) return undefined;
+	const [, major, minor, patch, changelist, branch] = match;
+	return {
+		major: Number(major),
+		minor: Number(minor),
+		patch: Number(patch),
+		changelist: Number(changelist ?? "0"),
+		branchName: branch,
+		raw: raw.trim(),
+	};
+}
+
+/** Stable cache key inputs for an index build. */
+export function indexSignature(index: PluginIndex): string {
+	const parts = [index.engineRoot ?? "-", index.projectDir ?? "-", index.scannedDirs.join(","), String(index.entries.length)];
+	return shortHash(parts.join("|"));
+}

package/extensions/unreal/lib/query.ts

@@ -0,0 +1,272 @@
+/**
+ * UBT Query orchestration: derive a target, cache the two Query JSON documents, and hand the parsed
+ * payload to the index layer.
+ *
+ * Two measurements drive this file:
+ *
+ * 1. **Query is expensive and asked for repeatedly.** `TargetDetails` for `LpEditor Win64 Development`
+ *    costs ~6 s and 40 MB of JSON; `TargetModuleReferences` ~3 s. Agents ask the same build question
+ *    dozens of times per session, so the JSON is cached in the pi cache dir
+ *    (`<cache>/query/<target>.<platform>.<config>/`), never in the project tree (1.5 GB of build
+ *    output is somebody else's problem) and never in git.
+ *
+ * 2. **`-NoIntellisense` voids the payload.** Measured: `dirToModule` survives, every
+ *    `moduleToCompileSettings` entry (defines, include paths, compiler args) and every `modules`
+ *    entry (source file lists) becomes `null`. The intellisense pass is what computes them, so this
+ *    file never passes that flag — the first run pays ~17 s, every later run pays 0.
+ *
+ * A target never has to be typed: `pickTarget` derives it from the `.uproject` `Modules` section,
+ * then plugin allowlists, then `*.Target.cs` files, then the engine editor target, and reports which
+ * rule matched.
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { joinPath, normalizePath, parentDir, baseName, realFs, type FsAdapter } from "./util.ts";
+import { cacheDir } from "./cache.ts";
+import { parseUproject } from "./descriptors.ts";
+import { findProjectFile } from "./engine-resolver.ts";
+import { discoverTargets, hostPlatform, parseModuleReferences, parseTargetDetails, pickDefaultTarget, readQueryJson, runQuery, type QueryName, type UbtModuleRefs, type TargetDetails } from "./ubt.ts";
+
+export interface TargetChoice {
+	target: string;
+	platform: string;
+	configuration: string;
+	/** Which rule produced the target — printed so a wrong guess is visible, not silent. */
+	source: "explicit" | "uproject-modules" | "plugin-allowlist" | "target-file" | "engine-editor" | "host-default";
+	notes: string[];
+}
+
+export interface CachePaths {
+	root: string;
+	targetDetails: string;
+	moduleReferences: string;
+}
+
+export interface QueryCacheState {
+	paths: CachePaths;
+	/** True when both documents exist and carry a payload (not the `-NoIntellisense` skeleton). */
+	usable: boolean;
+	targetDetails?: { path: string; bytes: number; ageMs: number };
+	moduleReferences?: { path: string; bytes: number; ageMs: number };
+	notes: string[];
+}
+
+export interface EnsureQueryInput {
+	cacheRoot?: string;
+	choice: TargetChoice;
+	engineRoot?: string;
+	projectPath?: string;
+	refresh?: boolean;
+	fs?: FsAdapter;
+	onStdout?: (chunk: string) => void;
+}
+
+export interface EnsureQueryResult {
+	paths?: CachePaths;
+	source: "cache" | "query" | "missing";
+	details?: TargetDetails;
+	refs?: Map<string, UbtModuleRefs>;
+	durationsMs: { targetDetails?: number; moduleReferences?: number };
+	notes: string[];
+	warnings: string[];
+}
+
+/* ───────────────────────────────────────────────────────────── target derivation */
+
+/**
+ * Derive (target, platform, configuration). Order of rules, first hit wins; the winning rule is
+ * reported. Explicit arguments always win, so a caller that knows better is never argued with.
+ */
+export function pickTarget(options: { cwd: string; target?: string; platform?: string; configuration?: string; engineRoot?: string; fs?: FsAdapter }): TargetChoice {
+	const fs = options.fs ?? realFs;
+	const platform = options.platform ?? hostPlatform();
+	const configuration = options.configuration ?? "Development";
+	const notes: string[] = [];
+	const projectPath = findProjectFile(options.cwd, fs);
+	const projectDir = projectPath ? parentDir(projectPath) : undefined;
+	const projectName = projectPath ? baseName(projectPath).replace(/\.uproject$/i, "") : undefined;
+	const targets = discoverTargets({ projectDir, engineRoot: options.engineRoot, projectDepth: 3, fs });
+
+	if (options.target) {
+		const known = targets.some((t) => t.name.toLowerCase() === options.target!.toLowerCase());
+		if (!known && projectDir) notes.push(`target '${options.target}' has no *.Target.cs under ${projectDir} (projectDir searched; a plugin or engine target may supply it)`);
+		return { target: options.target, platform, configuration, source: "explicit", notes };
+	}
+
+	// 1. The .uproject Modules section: a project module's editor target is the normal answer.
+	if (projectPath) {
+		const descriptor = parseUproject(projectPath, fs);
+		const modules = descriptor.modules.map((m) => m.moduleName);
+		if (modules.length) {
+		const editor = targets.find((t) => t.kind === "project" && modules.some((m) => t.name === `${m}Editor`) || t.kind === "project" && /editor$/i.test(t.name));
+			const exact = targets.find((t) => t.kind === "project" && modules.includes(t.name));
+			const chosen = editor ?? exact;
+			if (chosen) {
+				notes.push(`.uproject Modules = [${modules.join(", ")}] -> ${chosen.name}`);
+				return { target: chosen.name, platform, configuration, source: "uproject-modules", notes };
+			}
+			notes.push(`.uproject Modules = [${modules.join(", ")}] but no matching *.Target.cs under ${projectDir ?? "?"}`);
+		}
+
+		// 2. Plugin allowlists: an enabled plugin whose name matches a project target.
+		const enabled = descriptor.plugins.filter((p) => p.enabled !== false).map((p) => p.name);
+		const fromPlugin = targets.find((t) => t.kind === "project" && enabled.some((name) => t.name.toLowerCase().startsWith(name.toLowerCase())));
+		if (fromPlugin) {
+			notes.push(`matched enabled plugin -> ${fromPlugin.name}`);
+			return { target: fromPlugin.name, platform, configuration, source: "plugin-allowlist", notes };
+		}
+	}
+
+	// 3. Any project target, then the engine editor target, then a host-specific guess.
+	const projectTarget = pickDefaultTarget(targets.filter((t) => t.kind === "project"), projectName);
+	if (projectTarget) {
+		notes.push(`no .uproject Modules match; picked ${projectTarget.name} from *.Target.cs`);
+		return { target: projectTarget.name, platform, configuration, source: "target-file", notes };
+	}
+	const engineEditor = targets.find((t) => t.kind === "engine" && /editor/i.test(t.name));
+	if (engineEditor) {
+		notes.push(`no project target; engine editor target ${engineEditor.name}`);
+		return { target: engineEditor.name, platform, configuration, source: "engine-editor", notes };
+	}
+	// A guessed project target has no *.Target.cs to back it, so UBT would fail: report the
+	// guess, and make the failure mode explicit in the note.
+	const guess = `${projectName ?? "Target"}Editor`;
+	notes.push(`no *.Target.cs found for this project; guessed ${guess} — if UBT reports an unknown target, pass 'target' explicitly`);
+	return { target: guess, platform, configuration, source: "host-default", notes };
+}
+
+/* ──────────────────────────────────────────────────────────────────── the cache */
+
+export function queryCachePaths(choice: TargetChoice, root = cacheDir()): CachePaths {
+	const dir = joinPath(root, "query", `${choice.target}.${choice.platform}.${choice.configuration}`);
+	return { root: dir, targetDetails: joinPath(dir, "TargetDetails.json"), moduleReferences: joinPath(dir, "TargetModuleReferences.json") };
+}
+
+/** Payload check, not existence check: a `-NoIntellisense` document exists and is worthless. */
+function payloadOk(path: string, query: QueryName): boolean {
+	if (!existsSync(path)) return false;
+	try {
+		const json = readQueryJson(path) as Record<string, unknown> | undefined;
+		if (!json || typeof json !== "object") return false;
+		if (query === "TargetDetails") {
+			const settings = json.moduleToCompileSettings as Record<string, unknown> | undefined;
+			return !!settings && Object.keys(settings).length > 0;
+		}
+		const modules = json.modules as Record<string, unknown> | undefined;
+		return !!modules && Object.keys(modules).length > 0;
+	} catch {
+		return false;
+	}
+}
+
+function describe(path: string) {
+	const stat = statSync(path);
+	return { path, bytes: stat.size, ageMs: Math.max(0, Date.now() - stat.mtimeMs) };
+}
+
+export function queryCacheState(root: string, choice: TargetChoice, fs: FsAdapter = realFs): QueryCacheState {
+	void fs;
+	const paths = queryCachePaths(choice, root);
+	const notes: string[] = [];
+	const targetDetails = existsSync(paths.targetDetails) ? describe(paths.targetDetails) : undefined;
+	const moduleReferences = existsSync(paths.moduleReferences) ? describe(paths.moduleReferences) : undefined;
+	const detailsOk = targetDetails ? payloadOk(paths.targetDetails, "TargetDetails") : false;
+	const refsOk = moduleReferences ? payloadOk(paths.moduleReferences, "TargetModuleReferences") : false;
+	if (targetDetails && !detailsOk) notes.push(`cached TargetDetails has no moduleToCompileSettings payload — it was produced with -NoIntellisense, refresh it`);
+	if (moduleReferences && !refsOk) notes.push(`cached TargetModuleReferences has no modules payload — it was produced with -NoIntellisense, refresh it`);
+	if (!targetDetails || !moduleReferences) notes.push(`query cache empty for ${choice.target} ${choice.platform} ${choice.configuration}; the first Query costs ~17 s`);
+	return { paths, usable: detailsOk && refsOk, targetDetails, moduleReferences, notes };
+}
+
+/**
+ * Return parsed Query data, running UBT only when the cache cannot serve the request.
+ * `refresh` is the only way to re-run a usable cache; a missing cache is always filled.
+ */
+export async function ensureQueryJson(input: EnsureQueryInput): Promise<EnsureQueryResult> {
+	const fs = input.fs ?? realFs;
+	const root = input.cacheRoot ?? cacheDir(fs);
+	const paths = queryCachePaths(input.choice, root);
+	const notes: string[] = [];
+	const warnings: string[] = [];
+	const durationsMs: { targetDetails?: number; moduleReferences?: number } = {};
+	const state = queryCacheState(root, input.choice, fs);
+	notes.push(...state.notes);
+
+	if (state.usable && !input.refresh) {
+		const details = parseTargetDetails(readQueryJson(paths.targetDetails));
+		const refs = parseModuleReferences(readQueryJson(paths.moduleReferences));
+		notes.push(`query cache hit: ${Math.round((state.targetDetails?.bytes ?? 0) / 1024)} KB + ${Math.round((state.moduleReferences?.bytes ?? 0) / 1024)} KB, age ${humanAge(state.targetDetails?.ageMs ?? 0)}`);
+		return { paths, source: "cache", details, refs, durationsMs, notes, warnings };
+	}
+
+	if (!input.engineRoot) {
+		notes.push("no engine root resolved for this project, so Query cannot run");
+		return { source: "missing", durationsMs, notes, warnings };
+	}
+
+	const identity = {
+		target: input.choice.target,
+		platform: input.choice.platform,
+		configuration: input.choice.configuration,
+		projectPath: input.projectPath,
+	};
+	try {
+		mkdirSync(paths.root, { recursive: true });
+	} catch (error) {
+		warnings.push(`cannot create ${paths.root}: ${error instanceof Error ? error.message : String(error)}`);
+		return { source: "missing", durationsMs, notes, warnings };
+	}
+
+	const run = async (query: QueryName, dest: string) => {
+		const result = await runQuery({ ...identity, query, engineRoot: input.engineRoot!, outputPath: dest, fs, onStdout: input.onStdout });
+		durationsMs[query === "TargetDetails" ? "targetDetails" : "moduleReferences"] = result.durationMs;
+		if (result.json === undefined) {
+			warnings.push(`${query} failed (exit ${result.exitCode}, ${humanAge(result.durationMs)}): ${result.notes.join(" ")}`);
+			return undefined;
+		}
+		if (normalizePath(result.outputPath) !== normalizePath(dest)) {
+			// UBT wrote where it wanted (its `Writing <path>` line); mirror it into the cache.
+			try {
+				mkdirSync(parentDir(dest) ?? paths.root, { recursive: true });
+				writeFileSync(dest, readFileSync(result.outputPath, "utf8"), "utf8");
+			} catch (error) {
+				warnings.push(`${query}: cached copy failed (${error instanceof Error ? error.message : String(error)}); using ${result.outputPath}`);
+			}
+		}
+		const ok = payloadOk(dest, query) || payloadOk(result.outputPath, query);
+		if (!ok) warnings.push(`${query} produced JSON without a payload — UBT ran with intellisense disabled; rerun with refresh`);
+		notes.push(`${query}: ${humanAge(result.durationMs)} via ${result.ubtPath}`);
+		return result.json;
+	};
+
+	const detailsJson = await run("TargetDetails", paths.targetDetails);
+	if (detailsJson === undefined) return { source: "missing", durationsMs, notes, warnings };
+	const refsJson = await run("TargetModuleReferences", paths.moduleReferences);
+
+	const details = parseTargetDetails(detailsJson);
+	const refs = parseModuleReferences(refsJson ?? {});
+	return { paths, source: "query", details, refs, durationsMs, notes, warnings };
+}
+
+/** Compact rendering of a target choice, for tool output and the context card. */
+export function targetReport(choice: TargetChoice, state: QueryCacheState) {
+	return {
+		target: choice.target,
+		platform: choice.platform,
+		configuration: choice.configuration,
+		derivedFrom: choice.source,
+		notes: choice.notes,
+		cache: { dir: state.paths.root, usable: state.usable, targetDetailsBytes: state.targetDetails?.bytes, moduleReferencesBytes: state.moduleReferences?.bytes, age: state.targetDetails ? humanAge(state.targetDetails.ageMs) : undefined, notes: state.notes },
+	};
+}
+
+export function humanAge(ageMs: number): string {
+	if (!Number.isFinite(ageMs)) return "unknown";
+	const seconds = ageMs / 1000;
+	if (seconds < 90) return `${Math.round(seconds)}s`;
+	const minutes = seconds / 60;
+	if (minutes < 90) return `${Math.round(minutes)}min`;
+	const hours = minutes / 60;
+	if (hours < 48) return `${Math.round(hours)}h`;
+	return `${Math.round(hours / 24)}d`;
+}