perf(doctor): slim cold CLI/MCP doctor module graphs and run probes concurrently

Record default catalog counts and digests in recordedCatalogDigests.js, reuse
the SHA-256-verified mcp-catalog.json in default rea mcp doctor runs, move
Windows existing-project Ghidra admission constants to GhidraAdmission, defer
BinaryTargetResolver and Kuna installation probes until needed, and join
independent Doctor host/provider/identity probes via settleConcurrent.

Statically loaded JS drops 7.03 MB -> 2.07 MB (-70.6%) for rea doctor/setup
(command_ms 440ms -> 207ms, -53.0%) and 5.71 MB -> 0.85 MB (-85.1%) for
rea mcp doctor.
This commit is contained in:
morluto committed 2026-11-17 19:58:40 +08:00
1 parent de12494939
commit cb33fa8376
15 files changed
+445 -130

No files matched your search

+6 -3
View File
@@ -9,19 +9,22 @@ const compiledRoot = resolve(
dirname(fileURLToPath(import.meta.url)),
"../dist",
);
const { createCatalogDigestProfiles } = await import(
const { createCatalogDigestProfiles, DEFAULT_CATALOG_IDENTITY } = await import(
pathToFileURL(join(compiledRoot, "contracts/catalog/catalogIdentity.js")).href
);
// Retain only hashes, with every shared record frozen. Schemas remain owned by
// the compiled contracts and are converted once for both identities.
const profiles = Object.entries(createCatalogDigestProfiles())
const digestProfiles = createCatalogDigestProfiles();
const profiles = Object.entries(digestProfiles)
.map(
([output, digests]) =>
`${JSON.stringify(output)}: Object.freeze(${JSON.stringify(digests)})`,
)
.join(",");
const defaultCounts = JSON.stringify(DEFAULT_CATALOG_IDENTITY.counts);
const defaultDigests = JSON.stringify(digestProfiles.off);
await writeFile(
join(compiledRoot, "contracts/catalog/recordedCatalogDigests.js"),
`/** Recorded from compiled catalog profiles by scripts/record-catalog-digests.mjs; do not edit. */\nexport const RECORDED_CATALOG_DIGEST_PROFILES = Object.freeze({${profiles}});\n`,
`/** Recorded from compiled catalog profiles by scripts/record-catalog-digests.mjs; do not edit. */\nexport const RECORDED_CATALOG_DIGEST_PROFILES = Object.freeze({${profiles}});\nexport const RECORDED_DEFAULT_CATALOG_IDENTITY = Object.freeze({ counts: Object.freeze(${defaultCounts}), digests: Object.freeze(${defaultDigests}) });\n`,
"utf8",
);
+69
View File
@@ -7,6 +7,7 @@ import {
settledCause,
} from "../../tests/support/lifecycleHarness.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { cancelledBy } from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { createDoctorHostFixture } from "./Doctor.fixture.js";
import { runDoctorOwned, systemDoctorHost } from "./Doctor.js";
@@ -110,3 +111,71 @@ it("preserves an inspection-authored physical failure when final cleanup also ob
).rejects.toBe(physical);
expect(physical.cause).toBeUndefined();
});
it("joins concurrent sibling probes before closing and prefers physical failure over sibling cancellation", async () => {
const controller = new AbortController();
const siblingInFlight = phaseGate();
const refusedCleanup = controlledCleanup({ refused: true });
const physical = new ProviderAdapterError("jadx", "doctor", {
diagnostics: { reason: "concurrent provider fault" },
});
let closeStarted = false;
let siblingSettledBeforeClose = false;
const ownedSystem = systemDoctorHost({
signal: controller.signal,
platform: "darwin",
environment: {},
providerInspections: async (owner) => {
await siblingInFlight.hold();
siblingSettledBeforeClose = !closeStarted;
owner.retain(
{ close: () => refusedCleanup.close() },
"sibling-prerequisite",
);
throw physical;
},
});
const ownedHost = {
...ownedSystem,
macosVersion: async () => {
controller.abort({ request: "concurrent cancellation" });
throw cancelledBy("doctor", controller.signal);
},
close: async () => {
closeStarted = true;
return ownedSystem.close!();
},
};
const running = settledCause(runDoctorOwned(undefined, ownedHost));
await withVerifierCleanup(async () => {
await siblingInFlight.reached(running, "concurrent provider probe");
expect(closeStarted).toBe(false);
siblingInFlight.release();
const failure = await running;
expect(siblingSettledBeforeClose).toBe(true);
if (!(failure instanceof AnalysisError))
throw new Error("Expected attributed composite failure");
expect(failure.cleanupResources).toEqual(["sibling-prerequisite"]);
expect(failure.cleanupIncomplete).toBe(true);
expect(failure.diagnostics).toMatchObject({
primary_error: {
details: {
provider_id: "jadx",
diagnostics: { reason: "concurrent provider fault" },
},
},
});
refusedCleanup.allow();
await ownedHost.close();
expect(failure.cleanupIncomplete).toBe(false);
}, [
() => {
refusedCleanup.allow();
siblingInFlight.release();
},
async () => {
await running;
},
() => ownedHost.close(),
]);
});
+52 -23
View File
@@ -33,7 +33,6 @@ import { appendCallerPath } from "../filesystem/callerPath.js";
import { analysisErrorRemediationAction } from "../domain/analysisErrorPresentation.js";
import { BinaryTargetError } from "../domain/configurationErrors.js";
import { parseBinaryTarget } from "./BinaryTargetResolver.js";
import {
execFileOutput,
ExecFileOutputCancelledError,
@@ -61,7 +60,8 @@ import {
type InstalledSkillIdentity,
type SkillPathIssue,
} from "./SetupSkill.js";
import { DEFAULT_CATALOG_IDENTITY } from "../contracts/catalog/catalogIdentity.js";
import type { CatalogIdentitySnapshot } from "../contracts/catalog/recordedCatalogDigests.js";
import { loadDefaultCatalogIdentity } from "../contracts/catalog/defaultCatalogIdentity.js";
import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
import {
readClientRegistrationStatuses,
@@ -86,6 +86,7 @@ import type {
OwnedProviderSetting,
} from "../ports/DesktopBuildHost.js";
import { errorMessage } from "../kernel/errorMessage.js";
import { settleConcurrent } from "./settleConcurrent.js";
/** Read-only host capabilities required by diagnostics. */
export interface DoctorHost {
@@ -176,7 +177,7 @@ interface DoctorIdentity {
readonly expected_skill_version: string;
readonly sdk: typeof SDK_IDENTITY;
/** Package default advertisement; the active server reports its selected profile. */
readonly catalog: typeof DEFAULT_CATALOG_IDENTITY;
readonly catalog: CatalogIdentitySnapshot;
readonly live_server: {
readonly state: "unknown";
readonly remediation: string;
@@ -450,23 +451,43 @@ const collectDoctorIdentity = async (
readonly checks: readonly DoctorCheck[];
readonly value: DoctorIdentity;
}> => {
const launchers = (await host.installationLaunchers?.()) ?? [];
const registrations =
(await host.clientRegistrations?.(
scope.clients,
Object.fromEntries(
selections.flatMap(({ settings }) => Object.entries(settings)),
),
)) ?? [];
const skillClientIds =
scope.skill_clients ??
(scope.clients.length > 0 ? scope.clients : undefined);
const installedSkillIdentity =
await host.installedSkillIdentity?.(skillClientIds);
const skillAligned = skillIdentityAligned(installedSkillIdentity);
const [
resolvedLaunchers,
resolvedRegistrations,
installedSkillIdentity,
defaultCatalogIdentity,
] = await settleConcurrent([
Promise.resolve(host.installationLaunchers?.()),
Promise.resolve(
host.clientRegistrations?.(
scope.clients,
Object.fromEntries(
selections.flatMap(({ settings }) => Object.entries(settings)),
),
),
),
Promise.resolve(host.installedSkillIdentity?.(skillClientIds)),
loadDefaultCatalogIdentity(),
]);
const launchers = resolvedLaunchers ?? [];
const registrations = resolvedRegistrations ?? [];
const skillAligned = skillIdentityAligned(
installedSkillIdentity,
defaultCatalogIdentity.counts.mcp_tools,
);
return {
checks: [
...(skillAligned ? [] : [skillIdentityCheck(installedSkillIdentity)]),
...(skillAligned
? []
: [
skillIdentityCheck(
installedSkillIdentity,
defaultCatalogIdentity.counts.mcp_tools,
),
]),
...registrations
.filter(
(registration): registration is UnhealthyClientRegistrationStatus =>
@@ -479,8 +500,8 @@ const collectDoctorIdentity = async (
expected_skill_version: PRODUCT_IDENTITY.skillVersion,
sdk: SDK_IDENTITY,
catalog: {
counts: DEFAULT_CATALOG_IDENTITY.counts,
digests: DEFAULT_CATALOG_IDENTITY.digests,
counts: defaultCatalogIdentity.counts,
digests: defaultCatalogIdentity.digests,
},
live_server: {
state: "unknown",
@@ -498,7 +519,10 @@ const collectDoctorIdentity = async (
skill: {
installed_version: installedSkillIdentity?.version ?? null,
installed_tool_count: installedSkillIdentity?.toolCount ?? null,
state: skillIdentityState(installedSkillIdentity),
state: skillIdentityState(
installedSkillIdentity,
defaultCatalogIdentity.counts.mcp_tools,
),
...(installedSkillIdentity?.issues === undefined
? {}
: { issues: installedSkillIdentity.issues }),
@@ -513,13 +537,15 @@ const collectDoctorIdentity = async (
const skillIdentityAligned = (
identity: InstalledSkillIdentity | undefined,
expectedToolCount: number,
): boolean =>
identity?.version === PRODUCT_IDENTITY.skillVersion &&
identity.toolCount === DEFAULT_CATALOG_IDENTITY.counts.mcp_tools &&
identity.toolCount === expectedToolCount &&
identity.canonical;
const skillIdentityState = (
identity: InstalledSkillIdentity | undefined,
expectedToolCount: number,
): DoctorSkillState => {
if (
identity?.issues?.some(
@@ -538,7 +564,7 @@ const skillIdentityState = (
return "missing";
return identity === undefined
? "missing"
: skillIdentityAligned(identity)
: skillIdentityAligned(identity, expectedToolCount)
? "aligned"
: "stale";
};
@@ -562,17 +588,18 @@ const skillIdentityRemediation = (
const skillIdentityCheck = (
identity: InstalledSkillIdentity | undefined,
expectedToolCount: number,
): DoctorCheck => {
const issues = identity?.issues;
const state = skillIdentityState(identity, expectedToolCount);
return {
name: "skill:identity",
ok: false,
// An unreadable or unresolved copy is unknown, not proven drift.
classification:
skillIdentityState(identity) === "unknown" ? "unknown" : "config_drift",
classification: state === "unknown" ? "unknown" : "config_drift",
detail:
issues !== undefined && issues.length > 0
? `Selected skill identity is ${skillIdentityState(identity)}: ${issues.map(({ path }) => path).join(", ")}.`
? `Selected skill identity is ${state}: ${issues.map(({ path }) => path).join(", ")}.`
: identity === undefined
? "Installed REA skill identity is missing."
: "Installed REA skill identity is stale.",
@@ -751,6 +778,7 @@ export const systemDoctorHost = (
readMacosVersion(hostExecFileOutput, commandEnvironment),
linuxDistribution: () => readLinuxDistribution(architecture),
async validTarget(path) {
const { parseBinaryTarget } = await import("./BinaryTargetResolver.js");
return (
await parseBinaryTarget(path, {
cwd: process.cwd(),
@@ -759,6 +787,7 @@ export const systemDoctorHost = (
).ok;
},
async inspectTarget(path) {
const { parseBinaryTarget } = await import("./BinaryTargetResolver.js");
const result = await parseBinaryTarget(path, {
cwd: process.cwd(),
hostArchitecture: architecture,
+23 -7
View File
@@ -12,6 +12,7 @@ import type {
DoctorCheck,
DoctorProviderInspection,
} from "../ports/DoctorProviderInspection.js";
import { settleConcurrent } from "./settleConcurrent.js";
/** Ordered environment diagnostics consumed by the Doctor report assembler. */
export interface DoctorDiagnostics {
@@ -27,25 +28,40 @@ export const collectDoctorDiagnostics = async (
clients: readonly string[] = [],
): Promise<DoctorDiagnostics> => {
const checks: DoctorCheck[] = [nodeCheck(host)];
checks.push(await hostCheck(host));
const [
resolvedHostCheck,
hopperOutcome,
providerInspections,
ilspyCheck,
targetCheck,
] = await settleConcurrent([
hostCheck(host),
(async () => {
const hopperPath = await findHopper(host);
const [hopperVersionCheck, hopperDemoCheck] = await settleConcurrent([
optionalHopperVersionCheck(host, hopperPath),
optionalHopperDemoCheck(host, hopperPath),
]);
return { hopperPath, hopperVersionCheck, hopperDemoCheck };
})(),
Promise.resolve(host.providerInspections?.(clients ?? [])),
optionalIlspyCheck(host),
optionalTargetCheck(target, host),
]);
checks.push(resolvedHostCheck);
const hopperPath = await findHopper(host);
const { hopperPath, hopperVersionCheck, hopperDemoCheck } = hopperOutcome;
checks.push(hopperCheck(host, hopperPath));
const hopperTimeoutCheck = optionalHopperStartupTimeoutCheck(host);
if (hopperTimeoutCheck !== undefined) checks.push(hopperTimeoutCheck);
checks.push(...runtimeConfigurationChecks(host));
const hopperVersionCheck = await optionalHopperVersionCheck(host, hopperPath);
if (hopperVersionCheck !== undefined) checks.push(hopperVersionCheck);
const providerInspections = await host.providerInspections?.(clients ?? []);
if (providerInspections !== undefined)
checks.push(...providerInspections.flatMap(providerDoctorChecks));
const ilspyCheck = await optionalIlspyCheck(host);
if (ilspyCheck !== undefined) checks.push(ilspyCheck);
const hopperDemoCheck = await optionalHopperDemoCheck(host, hopperPath);
if (hopperDemoCheck !== undefined) checks.push(hopperDemoCheck);
const targetCheck = await optionalTargetCheck(target, host);
if (targetCheck !== undefined) checks.push(targetCheck);
return {
+29
View File
@@ -0,0 +1,29 @@
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
/**
* Join independent read-only inspections before surfacing any failure so peers
* finish handing retained resources to the owning scope first. Prefer physical
* failures and incomplete-cleanup attributions over plain cancellation.
*/
export const settleConcurrent = async <T extends readonly unknown[]>(tasks: {
[K in keyof T]: Promise<T[K]>;
}): Promise<T> => {
const settled = await Promise.allSettled(tasks);
const rejected = settled.flatMap((outcome) =>
outcome.status === "rejected" ? [outcome.reason] : [],
);
if (rejected.length > 0) {
const physical = rejected.find(
(cause) => !(cause instanceof AnalysisCancelledError),
);
if (physical !== undefined) throw physical;
const withCleanup = rejected.find(
(cause) => cause instanceof AnalysisError && cause.cleanupIncomplete,
);
throw withCleanup ?? rejected[0];
}
return settled.map((outcome) =>
outcome.status === "fulfilled" ? outcome.value : undefined,
) as unknown as T;
};
@@ -0,0 +1,14 @@
import {
RECORDED_DEFAULT_CATALOG_IDENTITY,
type CatalogIdentitySnapshot,
} from "./recordedCatalogDigests.js";
/**
* Resolve the package's default catalog counts and digests from the recorded
* build fact when available, falling back to live contract evaluation in
* uncompiled source runs.
*/
export const loadDefaultCatalogIdentity =
async (): Promise<CatalogIdentitySnapshot> =>
RECORDED_DEFAULT_CATALOG_IDENTITY ??
(await import("./catalogIdentity.js")).DEFAULT_CATALOG_IDENTITY;
+49
View File
@@ -0,0 +1,49 @@
import { createCatalogIdentity } from "./catalogIdentity.js";
import {
DISCOVER_TOOLS,
HOT_TOOL_NAMES,
progressiveCatalogIdentity,
} from "./catalogDiscovery.js";
import { contractsForToolFamilies } from "../toolFamilies.js";
import { toolContract } from "../toolContracts.js";
import { advertisedOutputJsonSchema } from "../toolSchemaMetadata.js";
import { promptsForToolFamilies } from "../promptToolFamilyScope.js";
import type { McpOutputSchemaProfile } from "../mcpSchemaPresentation.js";
import type { CatalogIdentitySnapshot } from "./recordedCatalogDigests.js";
export interface McpDoctorCatalogExpectation {
readonly catalog: CatalogIdentitySnapshot;
readonly expectedToolNames: readonly string[];
readonly expectedPromptNames: readonly string[];
readonly binarySessionOutputSchema: Record<string, unknown>;
}
/** Build expectations from live contracts when family selection or source runs require it. */
export const buildLiveMcpDoctorExpectation = (
selection: ReadonlySet<string> | undefined,
outputSchemaProfile: McpOutputSchemaProfile,
progressive: boolean,
): McpDoctorCatalogExpectation => {
const contracts = contractsForToolFamilies(selection);
const promptContracts = promptsForToolFamilies(selection);
const catalog = createCatalogIdentity({
contracts,
outputSchemaProfile,
promptContracts,
});
return {
catalog: progressive ? progressiveCatalogIdentity(catalog) : catalog,
expectedToolNames: progressive
? [
...contracts
.map(({ name }) => name)
.filter((name) => HOT_TOOL_NAMES.has(name)),
DISCOVER_TOOLS.name,
]
: contracts.map(({ name }) => name),
expectedPromptNames: promptContracts.map(({ name }) => name),
binarySessionOutputSchema: advertisedOutputJsonSchema(
toolContract("binary_session"),
),
};
};
@@ -11,6 +11,17 @@ export type CatalogDigestProfiles = Readonly<
Record<McpOutputSchemaProfile, CatalogDigests>
>;
export type CatalogCounts = {
readonly cli_commands: number;
readonly mcp_tools: number;
readonly mcp_prompts: number;
};
export type CatalogIdentitySnapshot = {
readonly counts: CatalogCounts;
readonly digests: CatalogDigests;
};
/**
* Digests of the two built-in output schema profiles over the compact input
* presentation, recorded from the compiled contracts by
@@ -20,3 +31,12 @@ export type CatalogDigestProfiles = Readonly<
export const RECORDED_CATALOG_DIGEST_PROFILES:
| CatalogDigestProfiles
| undefined = undefined;
/**
* Default catalog counts and digests recorded from the compiled contracts by
* `scripts/record-catalog-digests.mjs` so read-only CLI diagnostics do not load
* the complete contract registry. Source runs leave this undefined.
*/
export const RECORDED_DEFAULT_CATALOG_IDENTITY:
| CatalogIdentitySnapshot
| undefined = undefined;
+62 -38
View File
@@ -42,6 +42,7 @@ import {
inspectLinuxHopperPythonRuntime,
linuxHopperPythonUnavailable,
} from "./application/LinuxHopperPython.js";
import { settleConcurrent } from "./application/settleConcurrent.js";
/**
* A selected client's own environment, when its registration records one.
@@ -366,44 +367,67 @@ export const createSystemDoctorHost = (
environment,
platform,
);
return [
unresolvedProvider(
"ghidra",
selected,
inspectionEnvironment,
platform,
) ??
(await inspectSystemGhidraProvider(
inspectionEnvironment,
resourceScope,
inspectionSignal,
)),
unresolvedProvider("ida", selected, inspectionEnvironment, platform) ??
(await inspectIdaRegistration(
inspectionEnvironment.REA_IDA_MCP_CONFIG,
resourceScope,
inspectionSignal,
inspectionEnvironment.REA_IDA_MCP_CONFIG === undefined
? undefined
: readRegistration(
inspectionEnvironment.REA_IDA_MCP_CONFIG,
resourceScope,
inspectionSignal,
),
)),
unresolvedProvider("jadx", selected, inspectionEnvironment, platform) ??
(await inspectJadxProvider(
inspectionEnvironment,
resourceScope,
host,
inspectionSignal,
)),
unresolvedProvider("kuna", selected, inspectionEnvironment, platform) ??
(await inspectKunaProvider(inspectionEnvironment, platform, {
resourceScope,
signal: inspectionSignal,
})),
] satisfies readonly DoctorProviderInspection[];
const ghidraUnresolved = unresolvedProvider(
"ghidra",
selected,
inspectionEnvironment,
platform,
);
const idaUnresolved = unresolvedProvider(
"ida",
selected,
inspectionEnvironment,
platform,
);
const jadxUnresolved = unresolvedProvider(
"jadx",
selected,
inspectionEnvironment,
platform,
);
const kunaUnresolved = unresolvedProvider(
"kuna",
selected,
inspectionEnvironment,
platform,
);
return await settleConcurrent([
ghidraUnresolved !== undefined
? Promise.resolve(ghidraUnresolved)
: inspectSystemGhidraProvider(
inspectionEnvironment,
resourceScope,
inspectionSignal,
),
idaUnresolved !== undefined
? Promise.resolve(idaUnresolved)
: inspectIdaRegistration(
inspectionEnvironment.REA_IDA_MCP_CONFIG,
resourceScope,
inspectionSignal,
inspectionEnvironment.REA_IDA_MCP_CONFIG === undefined
? undefined
: readRegistration(
inspectionEnvironment.REA_IDA_MCP_CONFIG,
resourceScope,
inspectionSignal,
),
),
jadxUnresolved !== undefined
? Promise.resolve(jadxUnresolved)
: inspectJadxProvider(
inspectionEnvironment,
resourceScope,
host,
inspectionSignal,
),
kunaUnresolved !== undefined
? Promise.resolve(kunaUnresolved)
: inspectKunaProvider(inspectionEnvironment, platform, {
resourceScope,
signal: inspectionSignal,
}),
]);
},
desktopBuildFacts: readDesktopBuildFacts,
linuxDemoRuntimeCheck: (resourceScope, inspectionSignal) =>
+8
View File
@@ -8,6 +8,14 @@ import type {
UnavailableGhidraInstallation,
} from "./GhidraInstallation.js";
/** The selected database mode is not part of Windows P0 authority. */
export const EXISTING_PROJECT_WINDOWS_UNAVAILABLE =
"An existing Ghidra project cannot be opened on the Windows launch path.";
/** Windows P0 imports targets into ephemeral projects only. */
export const EXISTING_PROJECT_WINDOWS_REMEDIATION =
"Unset REA_GHIDRA_PROJECT_PATH in the environment that starts REA to import targets into an ephemeral project, or open the existing project on a supported Linux or macOS host; restart REA after changing the environment.";
/** Why Ghidra's local prerequisites refuse an inspected installation. */
export type GhidraAdmissionRefusal =
| {
+2 -2
View File
@@ -5,11 +5,11 @@ import type {
DoctorProviderCheck,
DoctorProviderInspection,
} from "../ports/DoctorProviderInspection.js";
import { admitGhidraInstallation } from "./GhidraAdmission.js";
import {
admitGhidraInstallation,
EXISTING_PROJECT_WINDOWS_REMEDIATION,
EXISTING_PROJECT_WINDOWS_UNAVAILABLE,
} from "./GhidraProviderCapabilities.js";
} from "./GhidraAdmission.js";
import {
inspectGhidraInstallation,
type GhidraInstallationCheck,
+9 -8
View File
@@ -8,6 +8,15 @@ import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionOperations.js";
import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryOperations.js";
import { GHIDRA_MUTATING_OPERATIONS } from "./GhidraSessionValues.js";
import { ghidraLoadImageVerificationNote } from "./GhidraVerifiedLoadImageFormats.js";
import {
EXISTING_PROJECT_WINDOWS_REMEDIATION,
EXISTING_PROJECT_WINDOWS_UNAVAILABLE,
} from "./GhidraAdmission.js";
export {
EXISTING_PROJECT_WINDOWS_REMEDIATION,
EXISTING_PROJECT_WINDOWS_UNAVAILABLE,
};
/** Target architectures admitted by the Windows P0 native PE boundary. */
export const WINDOWS_P0_NATIVE_PE_ARCHITECTURES: readonly string[] =
@@ -296,14 +305,6 @@ export const checkpointCapabilities = (): readonly CapabilityDescriptor[] =>
limitations: limitationsFor(capability.operation, "owned-checkpoint"),
}));
/** The selected database mode is not part of Windows P0 authority. */
export const EXISTING_PROJECT_WINDOWS_UNAVAILABLE =
"An existing Ghidra project cannot be opened on the Windows launch path.";
/** Windows P0 imports targets into ephemeral projects only. */
export const EXISTING_PROJECT_WINDOWS_REMEDIATION =
"Unset REA_GHIDRA_PROJECT_PATH in the environment that starts REA to import targets into an ephemeral project, or open the existing project on a supported Linux or macOS host; restart REA after changing the environment.";
/** Read-only project mode retains precise unavailable mutation capabilities. */
export const existingProjectCapabilities = (
platform: NodeJS.Platform,
+12 -7
View File
@@ -14,11 +14,9 @@ import type { RetainedResourceScope } from "../ports/AnalysisProvider.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { classifyProviderFailure } from "../providers/classifyProviderFailure.js";
import { kunaInstallationDialect } from "./KunaCommand.js";
import {
createKunaResourceScope,
inspectKunaInstallation,
type KunaReadinessFailure,
import type {
KunaReadinessFailure,
KunaResourceScope,
} from "./KunaInstallation.js";
import {
KUNA_COMMAND_REMEDIATION,
@@ -125,6 +123,8 @@ const versionCheck = async (
readonly version: string | null;
readonly check: DoctorProviderCheck;
}> => {
const { createKunaResourceScope, inspectKunaInstallation } =
await import("./KunaInstallation.js");
const kunaResources = createKunaResourceScope(options.resourceScope);
let installation: Awaited<ReturnType<typeof inspectKunaInstallation>>;
try {
@@ -134,7 +134,11 @@ const versionCheck = async (
...(options.signal === undefined ? {} : { signal: options.signal }),
});
} catch (cause: unknown) {
return { version: null, check: probeCleanupFailure(cause, kunaResources) };
const { kunaInstallationDialect } = await import("./KunaCommand.js");
return {
version: null,
check: probeCleanupFailure(cause, kunaResources, kunaInstallationDialect),
};
}
if (!installation.ok) {
const check = probeFailure(installation.error);
@@ -217,7 +221,8 @@ const cleanupIncompleteCheck = (
*/
const probeCleanupFailure = (
cause: unknown,
kunaResources: ReturnType<typeof createKunaResourceScope>,
kunaResources: KunaResourceScope,
kunaInstallationDialect: (typeof import("./KunaCommand.js"))["kunaInstallationDialect"],
): DoctorProviderCheck => {
let recognised = true;
const failure = classifyProviderFailure(
+89 -38
View File
@@ -1,11 +1,11 @@
import { Client, SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
import { OwnedMcpClient } from "./process/OwnedMcpClient.js";
import { formatCommandHelp } from "./cli/help.js";
import { readFileSync } from "node:fs";
import { performance } from "node:perf_hooks";
import { resolve } from "node:path";
import { StringDecoder } from "node:string_decoder";
import { createCatalogIdentity } from "./contracts/catalog/catalogIdentity.js";
import { jsonLinesErrorRecord } from "./cli/jsonLines.js";
import {
CLI_DOCUMENT_OUTPUT_FORMATS,
@@ -20,10 +20,15 @@ import {
HOT_TOOL_NAMES,
progressiveCatalogIdentity,
} from "./contracts/catalog/catalogDiscovery.js";
import { contractsForToolFamilies } from "./contracts/toolFamilies.js";
import { toolContract } from "./contracts/toolContracts.js";
import { advertisedOutputJsonSchema } from "./contracts/toolSchemaMetadata.js";
import { promptsForToolFamilies } from "./contracts/promptToolFamilyScope.js";
import {
RECORDED_CATALOG_DIGEST_PROFILES,
type CatalogIdentitySnapshot,
} from "./contracts/catalog/recordedCatalogDigests.js";
import {
RECORDED_MCP_CATALOG_SHA256,
type RecordedMcpCatalog,
} from "./recordedMcpCatalog.js";
import type { McpDoctorCatalogExpectation } from "./contracts/catalog/mcpDoctorCatalog.js";
import { err, ok } from "./domain/result.js";
import { AnalysisError } from "./domain/analysisErrorBase.js";
import { PRODUCT_IDENTITY } from "./identity.js";
@@ -38,6 +43,7 @@ import {
import { MCP_DOCTOR_ALIAS, MCP_DOCTOR_OPTIONS } from "./mcpDoctorOptions.js";
import { OwnedMcpStdioTransport } from "./process/OwnedMcpStdioTransport.js";
import { isRecord } from "./kernel/isRecord.js";
import { sha256Hex } from "./kernel/sha256Hex.js";
import { resolveMcpOutputSchemaProfile } from "./contracts/mcpSchemaPresentation.js";
import { errorMessage } from "./kernel/errorMessage.js";
@@ -111,7 +117,9 @@ export const runProductionMcpDoctor = async (options: McpDoctorOptions) => {
stderr_truncated: false,
},
};
const expectation = doctorExpectationForEnvironment(options.environment);
const expectation = await doctorExpectationForEnvironment(
options.environment,
);
const budget = parsedBudgets.value.doctor;
const budgetMs = budget.milliseconds;
const deadline = performance.now() + budgetMs;
@@ -236,13 +244,6 @@ class DoctorStdioTransport extends OwnedMcpStdioTransport {
const MCP_DOCTOR_SESSION_SCOPE_DETAIL =
"binary_session is outside the selected tool families; include the session family for request-flow and identity checks";
/** Doctor expectations derived from the same environment the child inherits. */
interface DoctorCatalogExpectation {
readonly catalog: ReturnType<typeof createCatalogIdentity>;
readonly expectedToolNames: readonly string[];
readonly expectedPromptNames: readonly string[];
}
const listPromptsWhenAdvertised = (
client: Client,
request: ReturnType<typeof requestOptions>,
@@ -255,7 +256,7 @@ const inspectProductionMcpSession = async (
client: Client,
deadline: number,
signal: AbortSignal,
expectation: DoctorCatalogExpectation,
expectation: McpDoctorCatalogExpectation,
budget: McpPhaseBudget,
) => {
const request = requestOptions(deadline, signal);
@@ -276,7 +277,7 @@ const inspectProductionMcpSession = async (
name: "binary_session",
inputSchema: { type: "object" as const },
}),
outputSchema: advertisedOutputJsonSchema(toolContract("binary_session")),
outputSchema: expectation.binarySessionOutputSchema,
};
// A scope without the session family cannot serve request flow at all;
// every other case still probes the call so the report names the real cause.
@@ -600,12 +601,43 @@ const targetFreeEnvironment = (
return result;
};
const doctorExpectationForEnvironment = (
let cachedVerifiedCatalog: RecordedMcpCatalog | null | undefined;
const readVerifiedRecordedMcpCatalog = (): RecordedMcpCatalog | undefined => {
if (cachedVerifiedCatalog !== undefined)
return cachedVerifiedCatalog ?? undefined;
if (RECORDED_MCP_CATALOG_SHA256 === undefined) {
cachedVerifiedCatalog = null;
return undefined;
}
try {
const bytes = readFileSync(new URL("./mcp-catalog.json", import.meta.url));
if (sha256Hex(bytes) !== RECORDED_MCP_CATALOG_SHA256) {
cachedVerifiedCatalog = null;
return undefined;
}
const parsed: unknown = JSON.parse(bytes.toString("utf8"));
if (!isRecord(parsed) || parsed.version !== 1) {
cachedVerifiedCatalog = null;
return undefined;
}
cachedVerifiedCatalog = parsed as unknown as RecordedMcpCatalog;
return cachedVerifiedCatalog;
} catch {
cachedVerifiedCatalog = null;
return undefined;
}
};
const doctorExpectationForEnvironment = async (
environment: Readonly<Record<string, string | undefined>>,
): DoctorCatalogExpectation => {
): Promise<McpDoctorCatalogExpectation> => {
const outputProfile = parseMcpOutputSchemaProfile(
environment.REA_MCP_OUTPUT_SCHEMA_PROFILE,
);
const resolvedOutputProfile = resolveMcpOutputSchemaProfile(
outputProfile.ok ? outputProfile.value : undefined,
);
// An invalid selection fails child startup, which the transport check
// reports with the server's diagnostics; expect the complete catalog so a
// failed start is never mistaken for a scope mismatch.
@@ -614,31 +646,50 @@ const doctorExpectationForEnvironment = (
families.ok && families.value !== undefined
? new Set(families.value)
: undefined;
const contracts = contractsForToolFamilies(selection);
const promptContracts = promptsForToolFamilies(selection);
const catalogProfile = parseMcpToolCatalogProfile(
environment.REA_MCP_TOOL_CATALOG_PROFILE,
);
const progressive = catalogProfile.ok && catalogProfile.value === "hot-cold";
const catalog = createCatalogIdentity({
contracts,
outputSchemaProfile: resolveMcpOutputSchemaProfile(
outputProfile.ok ? outputProfile.value : undefined,
),
promptContracts,
});
return {
catalog: progressive ? progressiveCatalogIdentity(catalog) : catalog,
expectedToolNames: progressive
? [
...contracts
.map(({ name }) => name)
.filter((name) => HOT_TOOL_NAMES.has(name)),
DISCOVER_TOOLS.name,
]
: contracts.map(({ name }) => name),
expectedPromptNames: promptContracts.map(({ name }) => name),
};
if (
selection === undefined &&
RECORDED_CATALOG_DIGEST_PROFILES !== undefined
) {
const recorded = readVerifiedRecordedMcpCatalog();
const sessionTool = recorded?.tools.find(
({ name }) => name === "binary_session",
);
if (
recorded !== undefined &&
sessionTool !== undefined &&
isRecord(sessionTool.outputSchema)
) {
const baseCatalog: CatalogIdentitySnapshot = {
counts: recorded.identity.counts,
digests: RECORDED_CATALOG_DIGEST_PROFILES[resolvedOutputProfile],
};
const toolNames = recorded.tools.map(({ name }) => name);
return {
catalog: progressive
? progressiveCatalogIdentity(baseCatalog)
: baseCatalog,
expectedToolNames: progressive
? [
...toolNames.filter((name) => HOT_TOOL_NAMES.has(name)),
DISCOVER_TOOLS.name,
]
: toolNames,
expectedPromptNames: recorded.prompts.map(({ name }) => name),
binarySessionOutputSchema: sessionTool.outputSchema,
};
}
}
const { buildLiveMcpDoctorExpectation } =
await import("./contracts/catalog/mcpDoctorCatalog.js");
return buildLiveMcpDoctorExpectation(
selection,
resolvedOutputProfile,
progressive,
);
};
const captureStderr = () => {
+1 -4
View File
@@ -88,10 +88,7 @@ const runCachedMcpDoctor = (
) =>
runProductionMcpDoctor({
...options,
environment:
options.environment === undefined
? undefined
: withCompileCache(options.environment),
environment: withCompileCache(options.environment),
});
const expectDoctorDeadline = (