rea-agents 2.0.0 → 2.1.0

package/dist/application/Setup.js

@@ -1,58 +1,47 @@
-import { access, copyFile, mkdir, readFile, rm, writeFile, } from "node:fs/promises";
-import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
-import { z } from "zod";
-import writeFileAtomic from "write-file-atomic";
-import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { supportsNodeVersion } from "../domain/runtimeVersion.js";
-import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 import { runDoctor, systemDoctorHost, } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 import { installMacHopper } from "./MacHopper.js";
 import { configureDetectedClients } from "./SetupClients.js";
 import { supportedClients } from "./SupportedClients.js";
 import { canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
-import { setupPlan } from "./SetupPlan.js";
+import { discoverSetupActions } from "./SetupPlan.js";
+import { clientConfigurationAligned, configureJsonClient, configureTomlClient, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
+export { configureJsonClient, configureTomlClient };
 import { setupInstallFailure, } from "./SetupInstallFailure.js";
-export { canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
+export { canonicalSkillNeedsInstall, installCanonicalSkill };
 const registrationCommand = () => process.env.npm_command === "exec"
-    ? ["npx", "-y", PRODUCT_IDENTITY.packageName, "mcp"]
+    ? ["npx", "-y", PRODUCT_IDENTITY.packageSpecifier, "mcp"]
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
-/**
- * Install prerequisites and configure detected clients idempotently.
- * Discovery always precedes mutation. Interactive confirmation or explicit
- * unattended options authorize only the actions represented in the result.
- */
+/** Discover, approve, and apply setup actions idempotently. */
 export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     const appliedActions = [];
     let plannedActions = [];
     const clients = {};
-    const fail = async (remediation) => ({
-        status: "needs_human",
-        plannedActions,
-        appliedActions,
-        clients,
-        doctor: await host.doctor(),
-        remediation,
-    });
+    const fail = (remediation) => setupFailure(remediation, [host, plannedActions, appliedActions, clients]);
     const unsupported = await hostRemediation(host, options.installHopper);
     if (unsupported !== undefined)
         return fail(unsupported);
     let hopperPath = await host.hopperPath();
     let providerEnvironment = await initialProviderEnvironment(host, hopperPath);
-    const discovery = await discoverSetupActions(host, providerEnvironment, options.installHopper);
-    const { installHopper, installSkill } = discovery;
-    let { detectedClients } = discovery;
-    plannedActions = discovery.plannedActions;
-    let approved = options.approved || plannedActions.length === 0;
-    let interactiveApproval = false;
-    if (!approved && confirm !== undefined && !options.structured) {
-        interactiveApproval = await confirm(plannedActions);
-        approved = interactiveApproval;
-    }
-    if (!approved)
+    const discovery = await discoverSetupActions({
+        host,
+        providerEnvironment,
+        command: registrationCommand(),
+        forceHopperInstall: options.installHopper,
+        proposeHopper: options.proposeHopper ?? true,
+        selectedClientIds: options.clientIds,
+        installSkillSelection: options.installSkill,
+    });
+    if (discovery.blocker !== undefined)
+        return fail(discovery.blocker);
+    const selection = await resolveSetupSelection(options, discovery, confirm);
+    plannedActions = selection.plannedActions;
+    if (!selection.approved)
         return {
             status: confirm === undefined ? "needs_confirmation" : "planned",
             plannedActions,
@@ -61,25 +50,21 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             doctor: await host.doctor(),
             remediation: "Review the setup plan, then rerun interactively or with --yes.",
         };
-    if (installHopper && (interactiveApproval || options.installHopper)) {
-        const installed = await host.installHopper(options.installHopper);
-        if (installed.status === "failed")
-            return {
-                status: "needs_human",
-                plannedActions,
-                appliedActions,
-                clients,
-                doctor: await host.doctor(),
-                code: installed.code,
-                remediation: installed.remediation,
-            };
-        hopperPath = installed.launcherPath;
-        providerEnvironment = {
-            ...providerEnvironment,
-            HOPPER_LAUNCHER_PATH: installed.launcherPath,
-        };
-        appliedActions.push("installed_hopper");
-        detectedClients = await filterClientsNeedingConfigure(host, detectedClients, providerEnvironment, registrationCommand());
+    let detectedClients = selection.detectedClients;
+    if (selection.installHopper &&
+        (selection.interactiveApproval || options.installHopper)) {
+        const install = await installHopperAction({
+            host,
+            options,
+            plannedActions,
+            appliedActions,
+            clients,
+            detectedClients,
+            providerEnvironment,
+        });
+        if ("failure" in install)
+            return install.failure;
+        ({ hopperPath, providerEnvironment, detectedClients } = install);
     }
     const clientFailure = await configureDetectedClients({
         host,
@@ -88,16 +73,15 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         command: registrationCommand(),
         clients,
         appliedActions,
+        ...(options.onProgress === undefined
+            ? {}
+            : { onProgress: options.onProgress }),
     });
     if (clientFailure !== undefined)
         return fail(clientFailure);
-    if (installSkill) {
-        const skill = await host.installSkill();
-        if (skill === "failed")
-            return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
-        if (skill === "installed")
-            appliedActions.push("installed_skill");
-    }
+    if (selection.installSkill &&
+        !(await installSkillAction(host, options, appliedActions)))
+        return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
     const doctor = await host.doctor();
     const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
     return {
@@ -109,30 +93,114 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         ...(remediation === undefined ? {} : { remediation }),
     };
 };
-const discoverSetupActions = async (host, providerEnvironment, forceHopperInstall) => {
-    const initialDoctor = await host.doctor();
-    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
-        (name === "hopper-demo-runtime" ||
-            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
-    const installHopper = forceHopperInstall ||
-        Object.keys(providerEnvironment).length === 0 ||
-        linuxHopperRepairNeeded;
-    const [detectedClients, installSkill] = await Promise.all([
-        host.detectedClients(),
-        host.skillNeedsInstall(),
-    ]);
-    const command = registrationCommand();
-    const clients = installHopper
-        ? detectedClients
-        : await filterClientsNeedingConfigure(host, detectedClients, providerEnvironment, command);
-    const plannedActions = setupPlan(host.platform, installHopper, installSkill, clients, providerEnvironment);
+const resolveSetupSelection = async (options, discovery, confirm) => {
+    let { installHopper, installSkill, detectedClients, plannedActions } = discovery;
+    let approved = options.approved || plannedActions.length === 0;
+    let interactiveApproval = false;
+    if (!approved && confirm !== undefined && !options.structured) {
+        const decision = await confirm(plannedActions);
+        if (typeof decision === "boolean") {
+            interactiveApproval = decision;
+            approved = decision;
+        }
+        else {
+            const selected = new Set(decision.selectedActionIds);
+            plannedActions = plannedActions.filter(({ id }) => selected.has(id));
+            installHopper = plannedActions.some(({ kind }) => kind === "install_hopper");
+            installSkill = plannedActions.some(({ kind }) => kind === "install_skill");
+            detectedClients = detectedClients.filter((client) => selected.has(`configure_client:${client.name}`));
+            interactiveApproval = decision.approved;
+            approved = decision.approved || plannedActions.length === 0;
+        }
+    }
     return {
+        approved,
+        interactiveApproval,
         installHopper,
         installSkill,
-        detectedClients: clients,
+        detectedClients,
         plannedActions,
     };
 };
+const installHopperAction = async (input) => {
+    const label = "Hopper deep-analysis provider";
+    emitProgress(input.options, {
+        actionId: "install_hopper",
+        label,
+        state: "started",
+    });
+    const installed = await input.host.installHopper(input.options.installHopper);
+    if (installed.status === "failed") {
+        emitProgress(input.options, {
+            actionId: "install_hopper",
+            label,
+            state: "failed",
+            detail: installed.remediation,
+        });
+        return {
+            failure: {
+                status: "needs_human",
+                plannedActions: input.plannedActions,
+                appliedActions: input.appliedActions,
+                clients: input.clients,
+                doctor: await input.host.doctor(),
+                code: installed.code,
+                remediation: installed.remediation,
+            },
+        };
+    }
+    input.appliedActions.push("installed_hopper");
+    emitProgress(input.options, {
+        actionId: "install_hopper",
+        label,
+        state: "completed",
+        detail: installed.launcherPath,
+    });
+    const providerEnvironment = {
+        ...input.providerEnvironment,
+        HOPPER_LAUNCHER_PATH: installed.launcherPath,
+    };
+    return {
+        hopperPath: installed.launcherPath,
+        providerEnvironment,
+        detectedClients: await filterClientsNeedingConfigure(input.host, input.detectedClients, providerEnvironment, registrationCommand()),
+    };
+};
+const installSkillAction = async (host, options, appliedActions) => {
+    const label = "REA reverse-engineering skill";
+    emitProgress(options, {
+        actionId: "install_skill",
+        label,
+        state: "started",
+    });
+    const skill = await host.installSkill();
+    if (skill === "failed") {
+        emitProgress(options, {
+            actionId: "install_skill",
+            label,
+            state: "failed",
+        });
+        return false;
+    }
+    if (skill === "installed")
+        appliedActions.push("installed_skill");
+    emitProgress(options, {
+        actionId: "install_skill",
+        label,
+        state: skill === "installed" ? "completed" : "warning",
+        ...(skill === "unchanged" ? { detail: "Already current" } : {}),
+    });
+    return true;
+};
+const setupFailure = async (remediation, [host, plannedActions, appliedActions, clients]) => ({
+    status: "needs_human",
+    plannedActions,
+    appliedActions,
+    clients,
+    doctor: await host.doctor(),
+    remediation,
+});
+const emitProgress = (options, event) => options.onProgress?.(event);
 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]);
@@ -202,6 +270,7 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
                 ? configureTomlClient(client, providerEnvironment, command)
                 : configureJsonClient(client, providerEnvironment, command),
         clientNeedsConfigure: (client, providerEnvironment, command) => clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
+        inspectClientConfiguration: inspectClientConfiguration,
         skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
         installSkill: () => installCanonicalSkill(homedir()),
         doctor: () => runDoctor(undefined, doctorHost),
@@ -215,133 +284,6 @@ export const detectClients = async (home) => {
             detected.push(candidate);
     return detected;
 };
-/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
-export const configureJsonClient = async (client, environment = {}, command = [
-    "npx",
-    "-y",
-    PRODUCT_IDENTITY.packageName,
-    "mcp",
-]) => {
-    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
-    if (transactionPath === undefined)
-        return { status: "failed", reason: "path" };
-    let document = {};
-    let original;
-    try {
-        original = await readFile(transactionPath, "utf8");
-        document = parseObject(original);
-    }
-    catch (cause) {
-        if (!isMissing(cause))
-            return { status: "failed", reason: "readback" };
-    }
-    let servers;
-    try {
-        servers = parseOptionalObject(document.mcpServers);
-    }
-    catch {
-        return { status: "failed", reason: "readback" };
-    }
-    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
-    if (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
-        JSON.stringify(desired))
-        return { status: "unchanged" };
-    let backupPath;
-    if (original !== undefined) {
-        backupPath = `${client.configPath}.rea.backup`;
-        if (!(await preserveConfigBackup(transactionPath, backupPath)))
-            return { status: "failed", reason: "backup" };
-    }
-    document.mcpServers = {
-        ...servers,
-        [PRODUCT_IDENTITY.mcpServerKey]: desired,
-    };
-    const encoded = `${JSON.stringify(document, null, 2)}\n`;
-    try {
-        await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFileAtomic(transactionPath, encoded, {
-            encoding: "utf8",
-            mode: 0o600,
-        });
-    }
-    catch {
-        return { status: "failed", reason: "write" };
-    }
-    try {
-        const readback = parseObject(await readFile(transactionPath, "utf8"));
-        const value = parseOptionalObject(readback.mcpServers)[PRODUCT_IDENTITY.mcpServerKey];
-        if (JSON.stringify(value) !== JSON.stringify(desired)) {
-            await restoreConfig(transactionPath, original);
-            return { status: "failed", reason: "readback" };
-        }
-    }
-    catch {
-        await restoreConfig(transactionPath, original);
-        return { status: "failed", reason: "readback" };
-    }
-    return {
-        status: "configured",
-        ...(backupPath === undefined ? {} : { backupPath }),
-    };
-};
-/** Back up, atomically update, and semantically read back Codex TOML configuration. */
-export const configureTomlClient = async (client, environment = {}, command = [
-    "npx",
-    "-y",
-    PRODUCT_IDENTITY.packageName,
-    "mcp",
-]) => {
-    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
-    if (transactionPath === undefined)
-        return { status: "failed", reason: "path" };
-    let document = {};
-    let original;
-    try {
-        original = await readFile(transactionPath, "utf8");
-        document = objectSchema.parse(parseToml(original));
-    }
-    catch (cause) {
-        if (!isMissing(cause))
-            return { status: "failed", reason: "readback" };
-    }
-    let servers;
-    try {
-        servers = parseOptionalObject(document.mcp_servers);
-    }
-    catch {
-        return { status: "failed", reason: "readback" };
-    }
-    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
-    if (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
-        JSON.stringify(desired))
-        return { status: "unchanged" };
-    const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
-    if (backupPath !== undefined &&
-        !(await preserveConfigBackup(transactionPath, backupPath)))
-        return { status: "failed", reason: "backup" };
-    document.mcp_servers = {
-        ...servers,
-        [PRODUCT_IDENTITY.mcpServerKey]: desired,
-    };
-    try {
-        await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFileAtomic(transactionPath, stringifyToml(document), {
-            encoding: "utf8",
-            mode: 0o600,
-        });
-        const readback = objectSchema.parse(parseToml(await readFile(transactionPath, "utf8")));
-        if (JSON.stringify(parseOptionalObject(readback.mcp_servers)[PRODUCT_IDENTITY.mcpServerKey]) !== JSON.stringify(desired))
-            throw new Error("TOML readback mismatch");
-    }
-    catch {
-        await restoreConfig(transactionPath, original);
-        return { status: "failed", reason: "readback" };
-    }
-    return {
-        status: "configured",
-        ...(backupPath === undefined ? {} : { backupPath }),
-    };
-};
 const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
 const exists = async (path) => {
     try {
@@ -352,60 +294,6 @@ const exists = async (path) => {
         return false;
     }
 };
-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 objectSchema = z.record(z.string(), z.unknown());
-const parseOptionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
-const parseObject = (text) => objectSchema.parse(JSON.parse(text));
-const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
-const restoreConfig = async (path, original) => {
-    try {
-        if (original === undefined)
-            await rm(path, { force: true });
-        else
-            await writeFile(path, original, { encoding: "utf8", mode: 0o600 });
-    }
-    catch {
-        // The backup remains available for the remediation reported by setup.
-    }
-};
-const clientConfigurationDesired = (providerEnvironment, command) => {
-    const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
-    return {
-        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
-        args: command.slice(1),
-        ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
-    };
-};
-const clientConfigurationAligned = async (client, providerEnvironment, command) => {
-    const desired = clientConfigurationDesired(providerEnvironment, command);
-    try {
-        const original = await readFile(client.configPath, "utf8");
-        if (client.format === "toml") {
-            const document = objectSchema.parse(parseToml(original));
-            const servers = parseOptionalObject(document.mcp_servers);
-            return (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
-                JSON.stringify(desired));
-        }
-        const document = parseObject(original);
-        const servers = parseOptionalObject(document.mcpServers);
-        return (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
-            JSON.stringify(desired));
-    }
-    catch {
-        return false;
-    }
-};
-const normalizeProviderEnvironment = (environment) => typeof environment === "string"
-    ? { HOPPER_LAUNCHER_PATH: environment }
-    : environment;
 const providerRegistrationEnvironment = (inspections) => Object.fromEntries(inspections
     .filter(({ available }) => available)
     .flatMap(({ registrationEnvironment }) => Object.entries(registrationEnvironment))