reverseport 0.0.0-stage → 1.2.0

package/dist/application/SetupClientConfiguration.js

@@ -0,0 +1,314 @@
+import { readClientPolicyBlock } from "./GeminiClientSettings.js";
+import { readClientConfigurationFiles } from "./ClientConfigurationFiles.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerListedDisabled, clientServerPath, legacyClientServerPath, OMP_DISABLED_SERVERS_KEY, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
+import { dshDocument, DshCordisDocument } from "./DshCordisPatch.js";
+import { constants as fsConstants } from "node:fs";
+import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { clientRegistrationEnvironment } from "./ClientRegistrationEnvironment.js";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
+import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
+import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
+import { readRegularFileText, RegularFileCleanupFailure, } from "./RegularFileRead.js";
+/** Configure one supported client's native stdio MCP registration shape. */
+export const configureClientConfiguration = (client, environment = {}, command = npxRegistrationCommand()) => {
+    if (client.configPathError !== undefined)
+        return Promise.resolve({ status: "failed", reason: "path" });
+    return configureClientDocument(client, environment, command);
+};
+const configureClientDocument = async (client, environment, command) => {
+    const format = client.format;
+    if (format === undefined || format === "unsupported")
+        return { status: "failed", reason: "readback" };
+    const files = await readClientConfigurationFiles(client);
+    if (!files.ok) {
+        throwCleanupFailure(files.error);
+        return { status: "failed", reason: "readback" };
+    }
+    const existing = files.value.at(-1);
+    const editabilityError = existing?.dialect === "dsh"
+        ? dshDocument(existing.document).editabilityError
+        : undefined;
+    if (editabilityError !== undefined)
+        return { status: "failed", reason: "readback" };
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, environment, command, files.value.at(-1)));
+    if (!policy.ok) {
+        throwCleanupFailure(policy.error);
+        return { status: "failed", reason: "readback" };
+    }
+    if (policy.value !== undefined)
+        return { status: "failed", reason: "readback" };
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return { status: "failed", reason: "path" };
+    let original;
+    try {
+        original = await readRegularFileText(transactionPath);
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        if (!isMissing(cause))
+            return { status: "failed", reason: "readback" };
+    }
+    let parsed;
+    try {
+        parsed = parseClientConfiguration(original ??
+            (format === "toml" || format === "grok" || format === "dsh"
+                ? ""
+                : "{}"), format);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, environment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return { status: "failed", reason: "readback" };
+        }
+        if (policy.value !== undefined)
+            return { status: "failed", reason: "readback" };
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        // Malformed existing configuration fails the readback gate.
+        void cause;
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = clientConfigurationDesired(client, environment, command, parsed);
+    if (registrationCurrent(parsed, desired))
+        return { status: "unchanged" };
+    return persistClientConfiguration({
+        client,
+        transactionPath,
+        format,
+        original,
+        parsed,
+        desired,
+    });
+};
+const persistClientConfiguration = async ({ client, transactionPath, format, original, parsed, desired, }) => {
+    const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
+    if (backupPath !== undefined &&
+        !(await preserveConfigBackup(transactionPath, backupPath)))
+        return { status: "failed", reason: "backup" };
+    // A native OpenCode V2 entry replaces REA's legacy V1 entry, which would
+    // otherwise conflict with it.
+    const legacyPath = legacyClientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey);
+    const registered = withClientServers(parsed, { ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired }, PRODUCT_IDENTITY.mcpServerKey);
+    // OMP's denylist would hide the registration; keep every other listed name.
+    const ompDisabled = parsed.dialect === "omp"
+        ? parsed.document[OMP_DISABLED_SERVERS_KEY]
+        : undefined;
+    const enableOmp = Array.isArray(ompDisabled) &&
+        ompDisabled.includes(PRODUCT_IDENTITY.mcpServerKey);
+    const document = enableOmp && Array.isArray(ompDisabled)
+        ? {
+            ...registered,
+            [OMP_DISABLED_SERVERS_KEY]: ompDisabled.filter((name) => name !== PRODUCT_IDENTITY.mcpServerKey),
+        }
+        : registered;
+    try {
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, [
+            clientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey),
+            ...(legacyPath === undefined ? [] : [legacyPath]),
+            ...(enableOmp ? [[OMP_DISABLED_SERVERS_KEY]] : []),
+        ]), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch (cause) {
+        // Write failure is reported by the status reason.
+        void cause;
+        return { status: "failed", reason: "write" };
+    }
+    try {
+        const readback = parseClientConfiguration(await readRegularFileText(transactionPath), format);
+        if (!registrationCurrent(readback, desired)) {
+            await restoreConfig(transactionPath, original);
+            return { status: "failed", reason: "readback" };
+        }
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        // Readback failure restores the transaction before reporting.
+        void cause;
+        await restoreConfig(transactionPath, original);
+        return { status: "failed", reason: "readback" };
+    }
+    return {
+        status: "configured",
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+};
+/** Determine whether an existing client configuration matches the desired registration. */
+export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
+    if (client.configPathError !== undefined)
+        return false;
+    try {
+        const files = await readClientConfigurationFiles(client);
+        if (!files.ok) {
+            throwCleanupFailure(files.error);
+            return false;
+        }
+        const original = await readRegularFileText(client.configPath);
+        const parsed = parseClientConfiguration(original, client.format);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return false;
+        }
+        return (policy.value === undefined &&
+            registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed)));
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        // Unreadable configuration is treated as not aligned so setup repairs it.
+        void cause;
+        return false;
+    }
+};
+/** Preflight one client configuration before setup presents any mutations. */
+export const inspectClientConfiguration = async (client, providerEnvironment, command) => {
+    if (client.configPathError !== undefined)
+        return { status: "invalid", remediation: client.configPathError };
+    if (client.format === "unsupported")
+        return { status: "already_current" };
+    const files = await readClientConfigurationFiles(client);
+    if (!files.ok) {
+        throwCleanupFailure(files.error);
+        return {
+            status: "invalid",
+            remediation: files.error.detail,
+        };
+    }
+    const existing = files.value.at(-1);
+    const editabilityError = existing?.dialect === "dsh"
+        ? dshDocument(existing.document).editabilityError
+        : undefined;
+    if (editabilityError !== undefined)
+        return {
+            status: "invalid",
+            remediation: editabilityError.message,
+        };
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, providerEnvironment, command, existing));
+    if (!policy.ok) {
+        throwCleanupFailure(policy.error);
+        return {
+            status: "invalid",
+            remediation: policy.error.detail,
+        };
+    }
+    if (policy.value !== undefined)
+        return { status: "invalid", remediation: policy.value };
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return {
+            status: "invalid",
+            remediation: "The configuration path is unsafe or unresolved. Check ownership and symbolic links before rerunning setup.",
+        };
+    let original;
+    try {
+        original = await readRegularFileText(transactionPath);
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        if (isMissing(cause))
+            return { status: "create" };
+        return {
+            status: "invalid",
+            remediation: `The configuration file could not be read. Check its permissions before rerunning setup. ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    try {
+        const parsed = parseClientConfiguration(original, client.format);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return {
+                status: "invalid",
+                remediation: policy.error.detail,
+            };
+        }
+        if (policy.value !== undefined)
+            return { status: "invalid", remediation: policy.value };
+        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed);
+        if (registrationCurrent(parsed, desired))
+            return { status: "already_current" };
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        // Malformed configuration is reported with the invalid remediation.
+        void cause;
+        return {
+            status: "invalid",
+            remediation: "The existing configuration is malformed. Repair it before setup applies any other changes.",
+        };
+    }
+    return {
+        status: "update",
+        backupPath: `${client.configPath}.rea.backup`,
+    };
+};
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const throwCleanupFailure = (error) => {
+    if (error.cleanupFailure !== undefined)
+        throw error.cleanupFailure;
+};
+const preserveConfigBackup = async (source, destination) => {
+    try {
+        await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+        return true;
+    }
+    catch (cause) {
+        return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+    }
+};
+const restoreConfig = async (path, original) => {
+    try {
+        if (original === undefined)
+            await rm(path, { force: true });
+        else
+            await writeFile(path, original, { encoding: "utf8", mode: 0o600 });
+    }
+    catch (cause) {
+        // The backup remains available for the remediation reported by setup.
+        void cause;
+    }
+};
+/** Whether REA's entry matches, no legacy entry remains, and no client disable list suppresses it. */
+const registrationCurrent = (parsed, desired) => (parsed.dialect !== "dsh" || dshDocument(parsed.document).ready) &&
+    clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) &&
+    !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey) &&
+    !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey);
+const clientConfigurationDesired = (client, providerEnvironment, command, parsed) => {
+    const format = parsed?.dialect ?? client.format ?? "json";
+    const launcher = command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command;
+    if (format === "dsh") {
+        const desired = (parsed === undefined
+            ? new DshCordisDocument("")
+            : dshDocument(parsed.document)).desired(launcher, providerEnvironment);
+        if (!desired.ok)
+            throw desired.error;
+        return desired.value;
+    }
+    // Preserve explicitly configured server settings, never the ambient process
+    // environment. Newly discovered provider paths win only for their own keys.
+    const environment = clientRegistrationEnvironment(parsed, providerEnvironment);
+    if (!environment.ok)
+        throw environment.error;
+    const registration = clientRegistrationEntry(format, launcher, environment.value);
+    return {
+        ...registration,
+        ...(client.name === "codex" || client.name === "grok_build"
+            ? {
+                startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
+            }
+            : {}),
+    };
+};

package/dist/application/SetupClients.js

@@ -0,0 +1,44 @@
+const failedConfigurationMessage = (reason) => {
+    if (reason === "path")
+        return "Agent configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun setup.";
+    if (reason === "backup")
+        return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";
+    if (reason === "write")
+        return "Agent configuration could not be updated. Check file permissions, then rerun setup.";
+    return "Agent configuration could not be verified after writing. Repair the configuration file or restore its `.rea.backup`, then rerun setup.";
+};
+/** Configure every detected agent and report the first failed transaction. */
+export const configureDetectedClients = async (options) => {
+    let failure;
+    for (const client of options.detectedClients) {
+        const actionId = `configure_client:${client.name}`;
+        const label = client.displayName ?? client.name;
+        options.onProgress?.({ actionId, label, state: "started" });
+        const result = await options.host.configureClient(client, options.providerEnvironment, options.command);
+        options.clients[client.name] = result;
+        if (result.status === "failed") {
+            failure ??= failedConfigurationMessage(result.reason);
+            options.onProgress?.({
+                actionId,
+                label,
+                state: "failed",
+                detail: failedConfigurationMessage(result.reason),
+            });
+        }
+        else if (result.status === "configured") {
+            options.appliedActions.push(`configured_${client.name}`);
+            options.onProgress?.({ actionId, label, state: "completed" });
+        }
+        else {
+            options.onProgress?.({
+                actionId,
+                label,
+                state: "warning",
+                detail: result.status === "unchanged"
+                    ? "Already current"
+                    : "Manual configuration required",
+            });
+        }
+    }
+    return failure;
+};

package/dist/application/SetupHost.js

@@ -0,0 +1,203 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { invokingPackageRunner, packageRunnerRegistrationCommand, } from "./ClientRegistrationIdentity.js";
+import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/runtimeVersion.js";
+import { runDoctor, systemDoctorHost } from "./Doctor.js";
+import { installLinuxHopper, readLinuxDistribution, systemLinuxHopperInstallHost, } from "./LinuxHopper.js";
+import { installMacHopper, systemMacHopperInstallHost } from "./MacHopper.js";
+import { clientEvidencePaths, supportedClients, } from "./SupportedClients.js";
+import { skillDestinations, canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
+import { clientConfigurationAligned, configureClientConfiguration, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
+import { setupInstallFailure } from "./SetupInstallFailure.js";
+import { RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
+import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";
+/** Resolve the executable and arguments used in a managed MCP registration. */
+export const setupRegistrationCommand = (platform, packageRunner) => packageRunner !== undefined
+    ? packageRunnerRegistrationCommand(packageRunner, platform)
+    : platform === "win32"
+        ? [
+            process.execPath,
+            resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary),
+            "mcp",
+        ]
+        : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
+export const filterClientsNeedingConfigure = async (host, detectedClients, providerEnvironment, command) => {
+    const needs = await Promise.all(detectedClients.map((client) => host.clientNeedsConfigure(client, providerEnvironment, command)));
+    return detectedClients.filter((_, index) => needs[index]);
+};
+export const hostRemediation = async (host, installHopper) => {
+    if (!supportsNodeVersion(host.nodeVersion))
+        return `Install ${SUPPORTED_NODE_VERSION_PROSE} and rerun setup.`;
+    if (!installHopper)
+        return undefined;
+    if (host.platform !== "darwin" && host.platform !== "linux")
+        return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
+    if (host.platform === "darwin") {
+        const version = await host.macosVersion();
+        return version === undefined || major(version) < 12
+            ? "Upgrade to macOS 12 or newer."
+            : undefined;
+    }
+    if ((await host.linuxDistribution())?.supported === true)
+        return undefined;
+    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, and Omarchy; configure an existing supported provider instead.";
+};
+/** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
+export const systemSetupHost = (selectedDoctorHost = undefined, environment = process.env) => {
+    const doctorHost = selectedDoctorHost ?? systemDoctorHost({ environment });
+    const platform = doctorHost.platform;
+    const { homeDirectory } = doctorHost;
+    const macHopperHost = platform === "darwin"
+        ? systemMacHopperInstallHost(homeDirectory, environment)
+        : undefined;
+    const resources = new ArtifactResourceScope();
+    return {
+        platform,
+        homeDirectory,
+        skillDestinations: (clientIds) => skillDestinations(homeDirectory, clientIds, environment, platform),
+        registrationCommand: setupRegistrationCommand(platform, invokingPackageRunner(environment, platform)),
+        nodeVersion: process.versions.node,
+        macosVersion: () => doctorHost.macosVersion(),
+        linuxDistribution: readLinuxDistribution,
+        close: () => closeSetupResources(resources, macHopperHost, doctorHost),
+        initialSetupState: async (scope) => {
+            const diagnosis = await runDoctor(undefined, doctorHost, scope);
+            return {
+                ...(diagnosis.hopperPath === undefined
+                    ? {}
+                    : { hopperPath: diagnosis.hopperPath }),
+                providerEnvironment: {
+                    ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
+                    ...(diagnosis.hopperPath === undefined
+                        ? {}
+                        : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
+                },
+                doctor: diagnosis,
+            };
+        },
+        installHopper: async (replaceExisting) => {
+            if (platform === "linux") {
+                const result = await installLinuxHopper(systemLinuxHopperInstallHost(environment));
+                return result.status === "installed"
+                    ? result
+                    : setupInstallFailure(result.reason);
+            }
+            if (macHopperHost === undefined)
+                return setupInstallFailure("unsupported_host");
+            const result = await installMacHopper({ replaceExisting }, macHopperHost);
+            if (result.status === "installed")
+                return {
+                    status: "installed",
+                    launcherPath: result.launcherPath,
+                    ...(result.cleanupFailure === undefined
+                        ? {}
+                        : { cleanupFailure: result.cleanupFailure }),
+                };
+            const failure = setupInstallFailure(result.reason);
+            if (result.cleanupFailure === undefined)
+                return failure;
+            return failure.status === "failed"
+                ? {
+                    ...failure,
+                    remediation: `${failure.remediation} ${result.cleanupFailure}`,
+                }
+                : failure;
+        },
+        detectedClients: () => detectClients(homeDirectory, platform, environment),
+        supportedClients: () => Promise.resolve(supportedClients(homeDirectory, platform, environment)),
+        ...clientConfigurationOperations(resources),
+        skillNeedsInstall: (clientIds) => canonicalSkillNeedsInstall(homeDirectory, clientIds, environment, platform, resources),
+        installSkill: (clientIds) => installCanonicalSkill(homeDirectory, clientIds, environment, platform, undefined, resources),
+        doctor: (scope) => runDoctor(undefined, doctorHost, scope),
+    };
+};
+const clientConfigurationOperations = (resources) => ({
+    configureClient: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, async () => client.format === "unsupported"
+        ? { status: "skipped" }
+        : configureClientConfiguration(client, providerEnvironment, command)),
+    clientNeedsConfigure: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, async () => client.format === "unsupported"
+        ? false
+        : !(await clientConfigurationAligned(client, providerEnvironment, command))),
+    inspectClientConfiguration: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, () => inspectClientConfiguration(client, providerEnvironment, command)),
+});
+const closeSetupResources = async (resources, macHopperHost, doctorHost) => {
+    const [resourceCleanup, hopperCleanup, doctorCleanup] = await Promise.allSettled([
+        resources.close(),
+        Promise.resolve().then(() => macHopperHost?.close()),
+        Promise.resolve().then(() => doctorHost.close?.()),
+    ]);
+    const failures = [];
+    if (hopperCleanup.status === "rejected")
+        failures.push(`Hopper host cleanup failed: ${errorMessage(hopperCleanup.reason)}`);
+    else if (hopperCleanup.value !== undefined)
+        failures.push(hopperCleanup.value);
+    if (doctorCleanup.status === "rejected")
+        failures.push(`Doctor host cleanup failed: ${errorMessage(doctorCleanup.reason)}`);
+    else if (doctorCleanup.value !== undefined)
+        failures.push(doctorCleanup.value);
+    if (resourceCleanup.status === "rejected")
+        failures.push(errorMessage(resourceCleanup.reason));
+    return failures.length === 0 ? undefined : failures.join("; ");
+};
+const runClientConfigurationOperation = async (resources, operation) => {
+    try {
+        return await resources.run(async () => {
+            try {
+                return await operation();
+            }
+            catch (cause) {
+                if (!(cause instanceof RegularFileCleanupFailure))
+                    throw cause;
+                const cleanup = await retryRegularFileCleanup(cause, resources);
+                const primary = cleanup.outcome.kind === "failed"
+                    ? cleanup.outcome.cause
+                    : cause.cleanupCause;
+                throw configurationCleanupError(`Could not safely access client configuration at ${cause.path}: ${errorMessage(primary)}`, cause, cleanup.cleanup);
+            }
+        });
+    }
+    catch (cause) {
+        if (cause instanceof ArtifactReaderFailure)
+            throw configurationCleanupError(cause.message, cause, cause.cleanup);
+        throw cause;
+    }
+};
+const configurationCleanupError = (message, cause, cleanup) => new ConfigurationError(message, {
+    cause,
+    settings: [{ setting: "client configuration", constraint: message }],
+    ...(cleanup === undefined ? {} : { cleanup }),
+});
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Detect supported agents from their config files or stable installation markers. */
+export const detectClients = async (home, platform = process.platform, environment = process.env) => {
+    const detected = [];
+    for (const candidate of supportedClients(home, platform, environment)) {
+        if (candidate.configPathError !== undefined)
+            continue;
+        if (await clientEvidencePresent(candidate))
+            detected.push(candidate);
+    }
+    return detected;
+};
+const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
+const clientEvidencePresent = async (client) => {
+    for (const path of clientEvidencePaths(client))
+        if (await exists(path))
+            return true;
+    return false;
+};
+const exists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (cause) {
+        // best-effort cleanup: optional host probing; absence means unavailable.
+        void cause;
+        return false;
+    }
+};

package/dist/application/SetupInstallFailure.js

@@ -0,0 +1,77 @@
+/** Map provider installer failures to stable setup codes and safe recovery. */
+export const setupInstallFailure = (reason) => {
+    switch (reason) {
+        case "unsupported_host":
+            return {
+                status: "failed",
+                code: "unsupported_host",
+                remediation: "Use a supported host, then rerun reverseport setup.",
+            };
+        case "integrity":
+            return {
+                status: "failed",
+                code: "integrity_mismatch",
+                remediation: "The Hopper download failed integrity verification. Retry setup; if it repeats, update REA before installing.",
+            };
+        case "authorization_or_package_manager":
+            return {
+                status: "failed",
+                code: "authorization_or_package_manager_failed",
+                remediation: "Allow the system package-manager operation or install the planned Hopper package and Linux runtime dependencies, then rerun reverseport setup.",
+            };
+        case "launcher_missing":
+            return {
+                status: "failed",
+                code: "launcher_missing",
+                remediation: "The package operation completed but Hopper is not runnable. Run reverseport doctor and repair the reported launcher issue.",
+            };
+        case "runtime_dependencies":
+            return {
+                status: "failed",
+                code: "runtime_dependency_unavailable",
+                remediation: "Hopper was installed but required shared libraries are missing. Rerun reverseport setup, then apply the hopper-demo-runtime remediation from reverseport doctor.",
+            };
+        case "unsupported_hopper_build":
+            return {
+                status: "failed",
+                code: "unsupported_hopper_build",
+                remediation: "The installed Hopper launcher does not match the build supported by this REA release. Unset HOPPER_LAUNCHER_PATH, reinstall through reverseport setup, or update REA.",
+            };
+        case "cancelled":
+            return {
+                status: "failed",
+                code: "setup_cancelled",
+                remediation: "Setup was cancelled before Hopper was installed. Rerun reverseport setup when ready.",
+            };
+        case "destination_exists":
+            return {
+                status: "failed",
+                code: "destination_exists",
+                remediation: "The Hopper installation destination already exists and was not replaced. Reuse the existing installation or move it aside, then rerun reverseport setup.",
+            };
+        case "mount":
+            return {
+                status: "failed",
+                code: "mount_failed",
+                remediation: "The verified Hopper disk image could not be mounted. Eject any stale Hopper image, check local disk access, then rerun reverseport setup.",
+            };
+        case "bundle":
+            return {
+                status: "failed",
+                code: "bundle_invalid",
+                remediation: "The mounted package did not contain the expected Hopper application bundle. Retry setup; if it repeats, update REA before installing.",
+            };
+        case "copy":
+            return {
+                status: "failed",
+                code: "copy_failed",
+                remediation: "The verified Hopper application could not be copied to the installation destination. Check destination permissions and free space, then rerun reverseport setup.",
+            };
+        default:
+            return {
+                status: "failed",
+                code: "download_failed",
+                remediation: "REA could not download or unpack the official Hopper package. Check network and filesystem access, then retry setup.",
+            };
+    }
+};