mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 04:34:13 +00:00
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:
1 parent
de12494939
commit
cb33fa8376
15 files changed
+445
-130
No files matched your search
@@ -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",
|
||||
);
|
||||
@@ -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
@@ -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,
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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;
|
||||
@@ -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
@@ -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,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 =
|
||||
| {
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
@@ -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
@@ -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 = () => {
|
||||
|
||||
@@ -88,10 +88,7 @@ const runCachedMcpDoctor = (
|
||||
) =>
|
||||
runProductionMcpDoctor({
|
||||
...options,
|
||||
environment:
|
||||
options.environment === undefined
|
||||
? undefined
|
||||
: withCompileCache(options.environment),
|
||||
environment: withCompileCache(options.environment),
|
||||
});
|
||||
|
||||
const expectDoctorDeadline = (
|
||||
|
||||
Reference in new issue
Block a user