diff --git a/src/ida/IdaAdmission.ts b/src/ida/IdaAdmission.ts new file mode 100644 index 0000000000..421f4c480a --- /dev/null +++ b/src/ida/IdaAdmission.ts @@ -0,0 +1,83 @@ +import { constants } from "node:fs"; +import { access, stat } from "node:fs/promises"; + +import { + privateRuntimeRootCapability, + type PrivateRuntimeRootCapability, +} from "../process/PrivateRuntimeRoot.js"; +import type { IdaConfiguration } from "./IdaConfiguration.js"; +import { resolveIdaWorkspaceParent } from "./IdaWorkspace.js"; + +/** The repair for a workspaceRoot REA cannot create entries in. */ +export const IDA_WORKSPACE_ROOT_REMEDIATION = + "Set workspaceRoot to an existing directory REA can create entries in, or omit it to use the system temporary directory; see docs/providers/ida-provider.md."; + +/** Why IDA's local prerequisites refuse a parsed registration. */ +export type IdaAdmissionRefusal = + | { + readonly kind: "private_workspace_unavailable"; + readonly privacy: Extract< + PrivateRuntimeRootCapability, + { readonly available: false } + >; + } + | { readonly kind: "workspace_unusable"; readonly reason: string }; + +/** + * IDA's admission of a parsed registration: the one decision doctor and the + * provider's readiness both project, so they cannot disagree. Attach mode + * needs nothing local. Headless mode needs private workspace authority and a + * workspace parent REA can create entries in. Nothing is created and IDA is + * not launched. + */ +export type IdaAdmission = + | { + readonly admitted: true; + /** The private workspace headless mode will allocate under. */ + readonly workspace?: { + readonly root: string | undefined; + readonly proof: string; + }; + } + | { + readonly admitted: false; + readonly workspaceRoot: string | undefined; + readonly refusal: IdaAdmissionRefusal; + }; + +export const admitIdaConfiguration = async ( + configuration: IdaConfiguration, +): Promise => { + if (configuration.mode !== "headless") return { admitted: true }; + const root = configuration.workspaceRoot; + const privacy = privateRuntimeRootCapability(); + if (!privacy.available) + return { + admitted: false, + workspaceRoot: root, + refusal: { kind: "private_workspace_unavailable", privacy }, + }; + const unusable = await workspaceParentUnusable(root); + return unusable === undefined + ? { admitted: true, workspace: { root, proof: privacy.proof } } + : { + admitted: false, + workspaceRoot: root, + refusal: { kind: "workspace_unusable", reason: unusable }, + }; +}; + +/** Resolve the workspace parent as allocation will, without creating entries. */ +const workspaceParentUnusable = async ( + root: string | undefined, +): Promise => { + try { + const parent = await resolveIdaWorkspaceParent(root); + if (!(await stat(parent)).isDirectory()) + return `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a directory.`; + await access(parent, constants.W_OK | constants.X_OK); + return undefined; + } catch (cause: unknown) { + return `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a usable directory: ${cause instanceof Error ? cause.message : String(cause)}`; + } +}; diff --git a/src/ida/IdaDoctor.ts b/src/ida/IdaDoctor.ts index 2a6bad2f3e..80d66a802c 100644 --- a/src/ida/IdaDoctor.ts +++ b/src/ida/IdaDoctor.ts @@ -6,9 +6,14 @@ import { readIdaConfiguration, type IdaConfiguration, } from "./IdaConfiguration.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import type { Result } from "../domain/result.js"; import type { ConfigurationError } from "../domain/configurationErrors.js"; -import { inspectIdaWorkspaceReadiness } from "./IdaWorkspaceReadiness.js"; +import { + admitIdaConfiguration, + IDA_WORKSPACE_ROOT_REMEDIATION, + type IdaAdmission, +} from "./IdaAdmission.js"; import type { RetainedResourceScope } from "../application/AnalysisProvider.js"; /** Client settings consulted by this readiness probe. */ @@ -30,14 +35,14 @@ export const inspectIdaRegistration = async ( ...(signal === undefined ? {} : { signal }), })); const valid = parsed?.ok === true; + const admission = + parsed?.ok === true ? await admitIdaConfiguration(parsed.value) : undefined; const workspaceChecks = - parsed?.ok === true && parsed.value.mode === "headless" - ? [await inspectPrivateWorkspace(parsed.value.workspaceRoot)] - : []; + admission === undefined ? [] : privateWorkspaceChecks(admission); return { id: "ida", configured: path !== undefined, - available: valid && workspaceChecks.every(({ ok }) => ok), + available: admission?.admitted === true, providerVersion: null, registrationEnvironment: valid && path !== undefined ? { REA_IDA_MCP_CONFIG: path } : {}, @@ -55,9 +60,12 @@ export const inspectIdaRegistration = async ( : parsed !== undefined && !parsed.ok ? parsed.error.message : "IDA MCP registration is not configured.", + // An invalid registration carries the repair runtime readiness reports. remediation: valid ? null - : "Set REA_IDA_MCP_CONFIG to your upstream IDA MCP registration JSON; see docs/providers/ida-provider.md.", + : parsed !== undefined && !parsed.ok + ? projectAnalysisError(parsed.error).remediation.action + : "Set REA_IDA_MCP_CONFIG to your upstream IDA MCP registration JSON; see docs/providers/ida-provider.md.", classification: path === undefined ? "missing_analysis_engine" : "config_drift", }, @@ -66,35 +74,57 @@ export const inspectIdaRegistration = async ( }; }; -const inspectPrivateWorkspace = async ( - workspaceRoot: string | undefined, -): Promise => { - const { privacy, unusable } = - await inspectIdaWorkspaceReadiness(workspaceRoot); - return { - name: "private_workspace", - ok: privacy.available && unusable === undefined, - code: !privacy.available - ? privacy.code - : unusable === undefined - ? null - : "invalid_configuration", - detail: !privacy.available - ? privacy.reason - : (unusable ?? - `Private workspace authority is available (${privacy.proof}) under ${workspaceRoot ?? "the system temporary directory"}.`), - remediation: !privacy.available - ? privacy.remediation - : unusable === undefined - ? null - : "Set workspaceRoot to an existing directory REA can create entries in, or omit it to use the system temporary directory; see docs/providers/ida-provider.md.", - classification: - !privacy.available && privacy.code === "runtime_missing" - ? "missing_dependency" - : !privacy.available && privacy.code === "runtime_unavailable" - ? "runtime_failure" - : unusable !== undefined - ? "config_drift" - : "unsupported_host", - }; +/** Project IDA's admission into the doctor's private workspace check. */ +const privateWorkspaceChecks = ( + admission: IdaAdmission, +): readonly DoctorProviderCheck[] => { + if (admission.admitted) + return admission.workspace === undefined + ? [] + : [ + { + name: "private_workspace", + ok: true, + code: null, + detail: `Private workspace authority is available (${admission.workspace.proof}) under ${admission.workspace.root ?? "the system temporary directory"}.`, + remediation: null, + classification: "unsupported_host", + }, + ]; + const { refusal } = admission; + switch (refusal.kind) { + case "workspace_unusable": + return [ + { + name: "private_workspace", + ok: false, + code: "invalid_configuration", + detail: refusal.reason, + remediation: IDA_WORKSPACE_ROOT_REMEDIATION, + classification: "config_drift", + }, + ]; + case "private_workspace_unavailable": { + const { privacy } = refusal; + return [ + { + name: "private_workspace", + ok: false, + code: privacy.code, + detail: privacy.reason, + remediation: privacy.remediation, + classification: + privacy.code === "runtime_missing" + ? "missing_dependency" + : privacy.code === "runtime_unavailable" + ? "runtime_failure" + : "unsupported_host", + }, + ]; + } + default: { + const unreachable: never = refusal; + return unreachable; + } + } }; diff --git a/src/ida/IdaProvider.test.ts b/src/ida/IdaProvider.test.ts index 4ab84847a1..bccd4d26c6 100644 --- a/src/ida/IdaProvider.test.ts +++ b/src/ida/IdaProvider.test.ts @@ -14,6 +14,7 @@ import { RecordingIdaMcp, createIdaTarget, } from "../../tests/fixtures/idaMcp.js"; +import { inspectIdaRegistration } from "./IdaDoctor.js"; import { IdaProvider } from "./IdaProvider.js"; it.each([ @@ -54,6 +55,19 @@ it.each([ expect(snapshot.availability.diagnostics).not.toHaveProperty( "configuration_remediation", ); + // Doctor reports the runtime's repair for a selected registration. + if (selected && snapshot.availability.status === "unavailable") { + const doctor = await inspectIdaRegistration(path, { + retain: () => undefined, + run: (operation) => operation(), + }); + expect( + doctor.checks.find(({ name }) => name === "registration"), + ).toMatchObject({ + ok: false, + remediation: snapshot.availability.remediation, + }); + } expect(connect).not.toHaveBeenCalled(); } finally { const closed = await provider.closeOwnedResources(); @@ -143,6 +157,25 @@ it.each(["missing", "file", "directory", "omitted"] as const)( )?.reason, ).toContain("direct call edges"); } else expect(snapshot.availability.status).toBe("available"); + // Doctor projects the same admission, so it agrees on the outcome, + // reason and repair. + const doctor = await inspectIdaRegistration(registration, { + retain: () => undefined, + run: (operation) => operation(), + }); + expect(doctor.available).toBe( + snapshot.availability.status === "available", + ); + const workspaceCheck = doctor.checks.find( + ({ name }) => name === "private_workspace", + ); + if (snapshot.availability.status === "unavailable") + expect(workspaceCheck).toMatchObject({ + ok: false, + detail: snapshot.availability.reason, + remediation: snapshot.availability.remediation, + }); + else expect(workspaceCheck).toMatchObject({ ok: true }); expect((await readdir(root)).sort()).toEqual(before); expect(connect).not.toHaveBeenCalled(); } finally { diff --git a/src/ida/IdaProvider.ts b/src/ida/IdaProvider.ts index 4e523a444e..3fa6cb6568 100644 --- a/src/ida/IdaProvider.ts +++ b/src/ida/IdaProvider.ts @@ -45,7 +45,11 @@ import { import { idaCapabilities } from "./IdaProviderCapabilities.js"; import { IDA_PROVIDER_IDENTITY } from "./IdaProviderMetadata.js"; import { IdaSessionClient } from "./IdaSessionClient.js"; -import { inspectIdaWorkspaceReadiness } from "./IdaWorkspaceReadiness.js"; +import { + admitIdaConfiguration, + IDA_WORKSPACE_ROOT_REMEDIATION, + type IdaAdmission, +} from "./IdaAdmission.js"; import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; @@ -234,38 +238,11 @@ export class IdaProvider implements AnalysisProviderCandidate { }, }); } - if (config.value.mode === "headless") { - const { privacy, unusable } = await inspectIdaWorkspaceReadiness( - config.value.workspaceRoot, + const admission = await admitIdaConfiguration(config.value); + if (!admission.admitted) + return unavailable( + idaRefusalAvailability(admission, registrationDiagnostics), ); - if (!privacy.available) - return unavailable({ - status: "unavailable", - code: privacy.code, - reason: privacy.reason, - remediation: privacy.remediation, - diagnostics: { - ...registrationDiagnostics, - mode: "headless", - private_workspace_available: false, - windows_native_failure: { stage: privacy.failureStage }, - }, - }); - if (unusable !== undefined) - return unavailable({ - status: "unavailable", - code: "open_options_invalid", - reason: unusable, - remediation: - "Set workspaceRoot to an existing directory REA can create entries in, or omit it to use the system temporary directory; see docs/providers/ida-provider.md.", - diagnostics: { - ...registrationDiagnostics, - mode: "headless", - workspace_root: config.value.workspaceRoot ?? null, - private_workspace_available: false, - }, - }); - } return { availability: { status: "available" as const, @@ -459,3 +436,43 @@ const readIdaConfigurationNotConfigured = () => "Set REA_IDA_MCP_CONFIG to an upstream IDA MCP JSON registration; see docs/providers/ida-provider.md.", ), ); + +/** Project IDA's admission refusal into provider availability. */ +const idaRefusalAvailability = ( + admission: Extract, + registrationDiagnostics: Readonly>, +): Extract => { + const { refusal } = admission; + switch (refusal.kind) { + case "private_workspace_unavailable": + return { + status: "unavailable", + code: refusal.privacy.code, + reason: refusal.privacy.reason, + remediation: refusal.privacy.remediation, + diagnostics: { + ...registrationDiagnostics, + mode: "headless", + private_workspace_available: false, + windows_native_failure: { stage: refusal.privacy.failureStage }, + }, + }; + case "workspace_unusable": + return { + status: "unavailable", + code: "open_options_invalid", + reason: refusal.reason, + remediation: IDA_WORKSPACE_ROOT_REMEDIATION, + diagnostics: { + ...registrationDiagnostics, + mode: "headless", + workspace_root: admission.workspaceRoot ?? null, + private_workspace_available: false, + }, + }; + default: { + const unreachable: never = refusal; + return unreachable; + } + } +}; diff --git a/src/ida/IdaWorkspaceReadiness.ts b/src/ida/IdaWorkspaceReadiness.ts deleted file mode 100644 index d8ceabcafd..0000000000 --- a/src/ida/IdaWorkspaceReadiness.ts +++ /dev/null @@ -1,22 +0,0 @@ -import { constants } from "node:fs"; -import { access, stat } from "node:fs/promises"; - -import { privateRuntimeRootCapability } from "../process/PrivateRuntimeRoot.js"; -import { resolveIdaWorkspaceParent } from "./IdaWorkspace.js"; - -/** Inspect local prerequisites without creating a workspace or launching IDA. */ -export const inspectIdaWorkspaceReadiness = async ( - root: string | undefined, -) => { - const privacy = privateRuntimeRootCapability(); - let unusable: string | undefined; - try { - const parent = await resolveIdaWorkspaceParent(root); - if (!(await stat(parent)).isDirectory()) - unusable = `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a directory.`; - else await access(parent, constants.W_OK | constants.X_OK); - } catch (cause: unknown) { - unusable = `IDA workspaceRoot ${root ?? "the system temporary directory"} is not a usable directory: ${cause instanceof Error ? cause.message : String(cause)}`; - } - return { privacy, unusable }; -};