* fix(build): emit no runtime imports for type-only bindings
Under verbatimModuleSyntax, an import whose specifiers all carry inline
`type` modifiers compiles to `import {} from "..."`, a side-effect import
that still resolves and evaluates the module. 78 compiled modules carried
one, including `import {} from "playwright-core"` in the browser scenario
session, which loaded Playwright's module graph at MCP startup.
Use top-level `import type` for these bindings and enable oxlint's
typescript/no-import-type-side-effects rule so the pattern cannot return.
Refs #1685
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* perf(mcp): load Playwright when a scenario launches, not at startup
The browser scenario and Electron active providers are constructed before
the stdio server serves, and both bound Playwright's launchers at module
load. Resolve `chromium` and `_electron` from playwright-core when a
capture opens instead, as the web module resolver already does.
MCP startup now resolves 1,312 modules (4,902 resolutions) instead of
1,598 (6,076) before reading the first request, and no longer loads
playwright-core. Provider construction, the tool catalog, and capability
inventory are unchanged.
A boundary test spawns the stdio server, initializes, lists tools, and
asserts playwright-core and isomorphic-git were not resolved; the CLI
probe now exercises the real launch path to prove detection.
Closes #1685
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
416 lines
20 KiB
TypeScript
416 lines
20 KiB
TypeScript
import {
|
|
AnalysisAccessDeniedError,
|
|
AnalysisArtifactChangedError,
|
|
AnalysisInputError,
|
|
AnalysisUnsupportedTargetError,
|
|
AnalysisResourceConstraintError,
|
|
} from "./analysisErrorCore.js";
|
|
import { ArtifactOperationError } from "./artifactOperationError.js";
|
|
import {
|
|
BinaryTargetError,
|
|
ConfigurationError,
|
|
NoBinaryOpenError,
|
|
} from "./configurationErrors.js";
|
|
import { BrowserObservationError } from "./browserObservationError.js";
|
|
import {
|
|
EvidenceFileError,
|
|
EvidenceIntegrityError,
|
|
EvidenceReferenceError,
|
|
AnalysisSnapshotMismatchError,
|
|
} from "./evidenceErrors.js";
|
|
import {
|
|
HopperRemoteError,
|
|
HopperProcessError,
|
|
HopperStartError,
|
|
HopperTimeoutError,
|
|
} from "./hopperErrors.js";
|
|
import { ProviderSelectionError } from "./providerSelectionError.js";
|
|
import { UnknownRegistryError } from "./unknownRegistryError.js";
|
|
import { providerRetryAction } from "./providerOperationHealth.js";
|
|
import type { AnalysisError, AnalysisErrorTag } from "./analysisErrorBase.js";
|
|
import type { AnalysisErrorProjection } from "./analysisErrorProjection.js";
|
|
|
|
export const analysisErrorRemediationAction = (
|
|
error: AnalysisError,
|
|
): string => {
|
|
if (error instanceof AnalysisSnapshotMismatchError)
|
|
return "Run analysis without this snapshot, then save a fresh snapshot using the intended artifact, provider, and analysis profile.";
|
|
if (error instanceof AnalysisUnsupportedTargetError)
|
|
return (
|
|
error.remediationAction ??
|
|
"Select a target supported by this operation or choose an operation supporting the reported target format."
|
|
);
|
|
if (error instanceof AnalysisResourceConstraintError)
|
|
return (
|
|
error.remediationAction ??
|
|
(error.resource === "transport"
|
|
? "Discover retained records with get_evidence_bundle and detail: summary, then inspect compatible records through inspect_analysis_view using an exact Evidence reference. Export complete retained session evidence through export_evidence_bundle to a caller-selected path, or use complete CLI JSON output. The connection remains usable."
|
|
: error.resource === "cpu"
|
|
? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."
|
|
: error.resource === "file-size"
|
|
? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."
|
|
: "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.")
|
|
);
|
|
if (error instanceof HopperTimeoutError)
|
|
return error.operation === undefined
|
|
? "Inspect Hopper for a loader or license dialog and review details.launcher. Correct the loader configuration or complete Hopper setup, then open the target again."
|
|
: error.providerState === "busy"
|
|
? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
|
|
: "Check binary_session for Hopper health, then retry the operation.";
|
|
if (error instanceof HopperProcessError)
|
|
return hopperProcessRemediation(error);
|
|
if (error instanceof HopperStartError)
|
|
return error.ownerRunId === undefined
|
|
? "Check the Hopper launcher and target details, then retry opening the target."
|
|
: `Use the active REA session ${error.ownerRunId} or close it before opening this target again.`;
|
|
if (error instanceof HopperRemoteError)
|
|
return error.diagnosticType === "invalid_request"
|
|
? "Correct the reported address, document, or arguments and retry."
|
|
: "Review the Hopper diagnostic details; correct the request or retry if the failure was transient.";
|
|
if (error instanceof EvidenceReferenceError)
|
|
return "Use an exact Evidence reference retained by this session, supply the complete inline Evidence, re-run its producer, or import its Evidence bundle. close_binary clears retained records.";
|
|
if (
|
|
error instanceof BinaryTargetError &&
|
|
error.constraint === "directory_requires_file"
|
|
)
|
|
return "For a JavaScript/Electron application directory, call analyze_javascript_application with input_path or run `rea analyze <directory>`. For binary analysis, select its executable file.";
|
|
if (
|
|
error instanceof AnalysisAccessDeniedError ||
|
|
(error instanceof BinaryTargetError && error.systemCode !== undefined)
|
|
)
|
|
return "Check the current process's read access to the selected path. Retry with a readable local file.";
|
|
if (error instanceof AnalysisArtifactChangedError)
|
|
return "Wait until the selected file is stable. For an active binary session, reopen the target with open_binary before retrying so REA acquires its current identity; for a CLI command or target-free tool, rerun the operation.";
|
|
if (error instanceof ConfigurationError && error.settings.length > 0)
|
|
return `Correct ${[...new Set(error.settings.map(({ setting }) => setting))].join(", ")} in the environment that starts REA (your shell or the MCP client's registration), then rerun.`;
|
|
if (error instanceof AnalysisInputError)
|
|
return "Correct the listed arguments and retry.";
|
|
if (error instanceof UnknownRegistryError && error.reason === "not-found")
|
|
return "Check that the unknown_id belongs to this session, then retry.";
|
|
return analysisErrorUserMessage(error);
|
|
};
|
|
|
|
export const analysisErrorCategory = (
|
|
error: AnalysisError,
|
|
): AnalysisErrorProjection["category"] => {
|
|
if (
|
|
error instanceof ProviderSelectionError &&
|
|
error.reason === "provider_unavailable"
|
|
)
|
|
return "unavailable";
|
|
if (error._tag === "ProcessCaptureError")
|
|
return error.userCategory ?? "execution_failure";
|
|
if (error instanceof BrowserObservationError)
|
|
return error.userCategory ?? browserErrorCategory(error.reason);
|
|
if (
|
|
error instanceof HopperRemoteError &&
|
|
error.diagnosticType === "invalid_request"
|
|
)
|
|
return "invalid_input";
|
|
if (
|
|
error instanceof HopperRemoteError &&
|
|
error.diagnosticType === "authorization"
|
|
)
|
|
return "unavailable";
|
|
if (error instanceof HopperProcessError || error instanceof HopperStartError)
|
|
return "unavailable";
|
|
if (error instanceof ArtifactOperationError)
|
|
return artifactErrorCategory(error.reason);
|
|
if (
|
|
error instanceof EvidenceFileError &&
|
|
(error.reason === "missing" ||
|
|
error.reason === "not-file" ||
|
|
error.reason === "exists")
|
|
)
|
|
return "invalid_input";
|
|
return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure";
|
|
};
|
|
|
|
const browserErrorCategory = (
|
|
reason: BrowserObservationError["reason"],
|
|
): AnalysisErrorProjection["category"] => {
|
|
if (reason === "cancelled") return "cancelled";
|
|
if (reason === "timeout") return "timeout";
|
|
if (reason === "payload_limit") return "truncated";
|
|
if (
|
|
reason === "target_not_found" ||
|
|
reason === "target_not_allowed" ||
|
|
reason === "target_changed" ||
|
|
reason === "endpoint_unreachable" ||
|
|
reason === "disconnected"
|
|
)
|
|
return "unavailable";
|
|
return "execution_failure";
|
|
};
|
|
|
|
const artifactErrorCategory = (
|
|
reason: ArtifactOperationError["reason"],
|
|
): AnalysisErrorProjection["category"] => {
|
|
if (reason === "integrity") return "integrity_mismatch";
|
|
if (reason === "limit") return "truncated";
|
|
if (reason === "cancelled") return "cancelled";
|
|
if (reason === "unavailable") return "unavailable";
|
|
return "execution_failure";
|
|
};
|
|
|
|
const STATIC_ERROR_CATEGORIES: Readonly<
|
|
Partial<Record<AnalysisErrorTag, AnalysisErrorProjection["category"]>>
|
|
> = {
|
|
AnalysisInputError: "invalid_input",
|
|
AnalysisAccessDeniedError: "unavailable",
|
|
AnalysisArtifactChangedError: "integrity_mismatch",
|
|
AnalysisCapabilityUnavailableError: "unsupported_provider",
|
|
AnalysisUnsupportedTargetError: "unsupported_target",
|
|
ProviderSelectionError: "unsupported_provider",
|
|
EvidenceIntegrityError: "integrity_mismatch",
|
|
AnalysisCancelledError: "cancelled",
|
|
HopperCancelledError: "cancelled",
|
|
AnalysisTimeoutError: "timeout",
|
|
AnalysisResourceConstraintError: "resource_constraint",
|
|
HopperTimeoutError: "timeout",
|
|
NoBinaryOpenError: "unavailable",
|
|
BinaryTargetError: "unavailable",
|
|
};
|
|
|
|
export const analysisErrorUserMessage = (error: AnalysisError): string => {
|
|
if (error instanceof AnalysisSnapshotMismatchError) return error.message;
|
|
if (error instanceof AnalysisUnsupportedTargetError) return error.message;
|
|
if (error instanceof AnalysisResourceConstraintError) return error.reason;
|
|
if (error instanceof AnalysisAccessDeniedError)
|
|
return "Host filesystem permissions denied read access to the selected path.";
|
|
if (error instanceof AnalysisArtifactChangedError)
|
|
return "The selected artifact changed during acquisition; no stable snapshot was decoded.";
|
|
if (error instanceof AnalysisInputError)
|
|
return "Analysis input is invalid. Check the arguments and try again.";
|
|
const hopperMessage = hopperErrorUserMessage(error);
|
|
if (hopperMessage !== undefined) return hopperMessage;
|
|
if (error.userMessage !== undefined) return error.userMessage;
|
|
const standardMessage = standardErrorMessage(error._tag);
|
|
if (standardMessage !== undefined) return standardMessage;
|
|
if (error instanceof ArtifactOperationError) return artifactMessage(error);
|
|
if (error instanceof EvidenceReferenceError)
|
|
return error.reason === "missing"
|
|
? `Evidence ${error.evidenceId} is not retained in this session. Supply complete inline Evidence, re-run its producer, or import its bundle before using this reference.`
|
|
: `Evidence ${error.evidenceId} does not match the requested reference (${error.reason}). Check the expected and actual identity in the diagnostic details.`;
|
|
if (error instanceof EvidenceIntegrityError)
|
|
return "Evidence is invalid or has changed. Recreate or re-import it, then try again.";
|
|
if (error instanceof EvidenceFileError) return evidenceFileMessage(error);
|
|
if (error instanceof UnknownRegistryError && error.reason === "not-found")
|
|
return "The requested residual unknown does not exist in this session. Check the unknown_id and try again.";
|
|
if (error instanceof UnknownRegistryError)
|
|
return "Evidence state changed before the update completed. Refresh the current state and try again.";
|
|
if (error instanceof ConfigurationError)
|
|
return error.settings.length === 0
|
|
? "REA configuration is invalid. Run `rea doctor` and fix the reported setting."
|
|
: `REA configuration is invalid: ${error.settings
|
|
.map(({ setting, constraint }) =>
|
|
constraint.includes(setting)
|
|
? constraint.replace(/\.$/u, "")
|
|
: `${setting}: ${constraint}`,
|
|
)
|
|
.join("; ")}.`;
|
|
if (error instanceof NoBinaryOpenError) return error.message;
|
|
if (error instanceof BinaryTargetError)
|
|
return error.constraint === "directory_requires_file"
|
|
? "open_binary accepts files and macOS app bundles. This target is a directory; JavaScript/Electron application directories can be analyzed directly with analyze_javascript_application or `rea analyze <directory>`."
|
|
: `${error.message}. Check that the path exists, is readable, and points to a supported file.`;
|
|
if (error._tag === "ProcessCaptureError")
|
|
return (
|
|
error.userMessage ??
|
|
"Process capture could not complete. Run `rea doctor`, then review capture policy and try again."
|
|
);
|
|
return "Analysis could not complete. Run `rea doctor`, then try again.";
|
|
};
|
|
|
|
const hopperErrorUserMessage = (error: AnalysisError): string | undefined => {
|
|
if (error instanceof HopperTimeoutError) {
|
|
if (error.operation === undefined)
|
|
return "REA timed out waiting for Hopper bridge readiness. Hopper may be waiting for a loader or license dialog; inspect its window and the captured launcher outcome before retrying.";
|
|
const request = error.operation;
|
|
return error.providerState === "busy"
|
|
? `Hopper timed out during ${request} while the provider remained busy. Check binary_session.analysis_activity, wait for the active request to finish, then retry.`
|
|
: `Hopper timed out during ${request} before it started. Check binary_session for provider health, then retry.`;
|
|
}
|
|
if (error instanceof HopperProcessError) return hopperProcessMessage(error);
|
|
if (error instanceof HopperStartError)
|
|
return (
|
|
error.userMessage ??
|
|
"Hopper could not start. Check the launcher and target details, then retry opening the target."
|
|
);
|
|
if (error instanceof HopperRemoteError)
|
|
return `Hopper ${error.operation ?? "analysis"} failed (${String(error.code)}, ${error.diagnosticType}): ${error.safeMessage}`;
|
|
return undefined;
|
|
};
|
|
|
|
const RESTART_OWNED_PROVIDER =
|
|
"Restart the owned provider by calling close_binary, then open the target again and retry.";
|
|
|
|
const hopperProcessRemediation = (error: HopperProcessError): string => {
|
|
if (error.failureCode !== undefined && error.userMessage !== undefined)
|
|
return error.userMessage;
|
|
if (error.stage === "launch")
|
|
return "Review the captured launcher diagnostics and Hopper setup, then retry opening the target.";
|
|
if (providerRetryAction(error.providerState) === "restart_provider")
|
|
return RESTART_OWNED_PROVIDER;
|
|
return "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider.";
|
|
};
|
|
|
|
const hopperProcessMessage = (error: HopperProcessError): string => {
|
|
const stage = error.stage;
|
|
const where = error.operation ?? stage;
|
|
const request =
|
|
error.requestId === undefined
|
|
? ""
|
|
: ` Request id ${String(error.requestId)}.`;
|
|
const startup =
|
|
error.userMessage === undefined ? "" : ` ${error.userMessage}`;
|
|
if (error.providerState === "exited") {
|
|
const exit =
|
|
error.exitCode === null
|
|
? "no exit code was observed"
|
|
: `exit code ${String(error.exitCode)}`;
|
|
const recovery =
|
|
error.failureCode === undefined && stage !== "launch"
|
|
? ` ${RESTART_OWNED_PROVIDER}`
|
|
: "";
|
|
return `Hopper exited during ${where} (${exit}).${startup}${recovery}${request}`;
|
|
}
|
|
if (error.providerState === "unreachable")
|
|
return `Hopper became unreachable during ${where}; its process exit was not observed. ${RESTART_OWNED_PROVIDER}${startup}${request}`;
|
|
return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup} Read binary_session.provider_operation_health for this request before retrying or restarting.${request}`;
|
|
};
|
|
|
|
const standardErrorMessage = (tag: AnalysisErrorTag): string | undefined => {
|
|
if (UNREADABLE_OUTPUT_TAGS.has(tag))
|
|
return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
|
|
if (UNSUPPORTED_PROVIDER_TAGS.has(tag))
|
|
return "This analysis is unavailable for the current target. Choose another analysis or target.";
|
|
if (CANCELLED_TAGS.has(tag))
|
|
return "Analysis was cancelled. Start it again when ready.";
|
|
if (TIMEOUT_TAGS.has(tag))
|
|
return "Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.";
|
|
if (ADAPTER_FAILURE_TAGS.has(tag))
|
|
return "Analysis could not complete. Retry once; if it continues, run `rea doctor`.";
|
|
if (START_FAILURE_TAGS.has(tag))
|
|
return "Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.";
|
|
return undefined;
|
|
};
|
|
|
|
const UNREADABLE_OUTPUT_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
|
|
"AnalysisProtocolError",
|
|
"AnalysisOutputError",
|
|
"HopperProtocolError",
|
|
]);
|
|
const UNSUPPORTED_PROVIDER_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
|
|
"AnalysisCapabilityUnavailableError",
|
|
"ProviderSelectionError",
|
|
]);
|
|
const CANCELLED_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
|
|
"AnalysisCancelledError",
|
|
"HopperCancelledError",
|
|
]);
|
|
const TIMEOUT_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
|
|
"AnalysisTimeoutError",
|
|
"HopperTimeoutError",
|
|
]);
|
|
const ADAPTER_FAILURE_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
|
|
"ProviderAdapterError",
|
|
"HopperRemoteError",
|
|
]);
|
|
const START_FAILURE_TAGS: ReadonlySet<AnalysisErrorTag> = new Set([
|
|
"HopperProcessError",
|
|
"HopperStartError",
|
|
]);
|
|
|
|
/** Operations that accept integrity_policy for declared-integrity mismatches. */
|
|
const INTEGRITY_POLICY_OPERATIONS: ReadonlySet<
|
|
ArtifactOperationError["operation"]
|
|
> = new Set([
|
|
"inventory_artifact",
|
|
"inspect_artifact",
|
|
"extract_artifact",
|
|
"analyze_javascript_application",
|
|
]);
|
|
|
|
const artifactMessage = ({
|
|
operation,
|
|
reason,
|
|
artifactDetails: details,
|
|
detail,
|
|
}: ArtifactOperationError): string => {
|
|
if (reason === "cancelled")
|
|
return "Artifact operation was cancelled. Start it again when ready.";
|
|
if (reason === "limit")
|
|
return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
|
|
if (reason === "path")
|
|
return (
|
|
detail ??
|
|
"Artifact contains a conflicting internal path. Inspect the reported path before retrying."
|
|
);
|
|
if (reason === "unavailable" && details?.unpacked === true)
|
|
return `ASAR unpacked companion bytes are unavailable for ${details.logicalPath}. Select the archive in place with its .unpacked directory beside it, then retry.`;
|
|
if (reason === "unavailable")
|
|
return "Artifact processing is unavailable for the current target or host. Check artifact support and required tools.";
|
|
if (reason === "integrity" && INTEGRITY_POLICY_OPERATIONS.has(operation))
|
|
return `${
|
|
details?.unpacked === true && details.calculatedSha256 !== null
|
|
? `Declared ASAR integrity for unpacked entry ${details.logicalPath} contradicts its companion file; packaging tools commonly sign or strip unpacked native binaries after writing the archive.`
|
|
: "Artifact bytes contradict declared integrity."
|
|
} If expected, rerun ${operation === "inventory_artifact" ? "inspect_artifact" : operation} with integrity_policy=record-and-continue (CLI: --integrity-policy record-and-continue) to retain observed bytes as untrusted; otherwise get a fresh copy.`;
|
|
if (reason === "format" || reason === "integrity")
|
|
return "Artifact is invalid or has changed. Get a fresh copy and try again.";
|
|
return "Artifact could not be read or written. Check file access and try again.";
|
|
};
|
|
|
|
const evidenceFileMessage = ({
|
|
operation,
|
|
reason,
|
|
}: EvidenceFileError): string => {
|
|
if (reason === "missing")
|
|
return operation === "read"
|
|
? "Evidence file does not exist at the selected path. Check the path and try again."
|
|
: "Evidence output directory does not exist. Choose an existing directory and try again.";
|
|
if (reason === "not-file")
|
|
return "Evidence path does not point to a regular file. Choose a file and try again.";
|
|
if (reason === "exists")
|
|
return "Evidence file already exists. Choose another path or allow overwrite.";
|
|
if (reason === "invalid-json")
|
|
return "Evidence file is not valid JSON. Repair or recreate the file and try again.";
|
|
return "Evidence file could not be accessed. Check file permissions and try again.";
|
|
};
|
|
|
|
const KNOWN_ERROR_TAGS = {
|
|
AnalysisProtocolError: true,
|
|
AnalysisInputError: true,
|
|
AnalysisAccessDeniedError: true,
|
|
AnalysisArtifactChangedError: true,
|
|
AnalysisOutputError: true,
|
|
AnalysisCapabilityUnavailableError: true,
|
|
AnalysisUnsupportedTargetError: true,
|
|
AnalysisCancelledError: true,
|
|
AnalysisTimeoutError: true,
|
|
AnalysisResourceConstraintError: true,
|
|
ProviderSelectionError: true,
|
|
ProviderAdapterError: true,
|
|
BrowserObservationError: true,
|
|
ArtifactOperationError: true,
|
|
ProcessCaptureError: true,
|
|
EvidenceIntegrityError: true,
|
|
EvidenceFileError: true,
|
|
UnknownRegistryError: true,
|
|
HopperTimeoutError: true,
|
|
HopperCancelledError: true,
|
|
HopperProtocolError: true,
|
|
HopperRemoteError: true,
|
|
HopperProcessError: true,
|
|
HopperStartError: true,
|
|
ConfigurationError: true,
|
|
NoBinaryOpenError: true,
|
|
BinaryTargetError: true,
|
|
} as const satisfies Readonly<Record<AnalysisErrorTag, true>>;
|
|
|
|
export const assertKnownAnalysisErrorTag = (tag: AnalysisErrorTag): void => {
|
|
if (KNOWN_ERROR_TAGS[tag] !== true)
|
|
throw new TypeError("Unknown analysis error tag");
|
|
};
|