rea-agents 6.4.0 → 6.7.0

package/dist/application/Update.js

@@ -1,30 +1,30 @@
 import { gt, valid } from "semver";
 import { PRODUCT_IDENTITY } from "../identity.js";
-/** Whether the update command left the requested release unapplied. */
-export const isUpdateFailure = (result) => {
-    const status = result.status;
-    switch (status) {
-        case "current":
-        case "updated":
-            return false;
-        case "failed":
-            return true;
+export { isUpdateFailure } from "./UpdateFailure.js";
+/** Resolve the exact package-manager command for the identified installation and release. */
+export const updateInstallCommand = (installation, version) => {
+    const release = `${PRODUCT_IDENTITY.packageName}@${version}`;
+    const manager = installation.manager;
+    switch (manager) {
+        case "npm":
+            return [
+                "npm",
+                "install",
+                "--global",
+                "--ignore-scripts",
+                "--prefix",
+                installation.prefix,
+                release,
+            ];
+        case "bun":
+            // The host pins Bun's global directory and working directory for this command.
+            return ["bun", "add", "--global", "--ignore-scripts", release];
         default: {
-            const exhaustive = status;
-            throw new TypeError(`Unhandled update result status: ${String(exhaustive)}`);
+            const exhaustive = manager;
+            throw new TypeError(`Unhandled installation manager: ${String(exhaustive)}`);
         }
     }
 };
-/** Resolve the exact npm command for the identified prefix and release. */
-export const updateInstallCommand = (installation, version) => [
-    "npm",
-    "install",
-    "--global",
-    "--ignore-scripts",
-    "--prefix",
-    installation.prefix,
-    `${PRODUCT_IDENTITY.packageName}@${version}`,
-];
 const versionCheckRemediation = (release) => {
     if (release.ok) {
         return "REA received invalid version metadata. Check the installed version and npm registry, then rerun rea update.";
@@ -32,6 +32,8 @@ const versionCheckRemediation = (release) => {
     const failure = release.error;
     const kind = failure.kind;
     switch (kind) {
+        case "unsupported-package-manager":
+            return failure.detail;
         case "unavailable":
             return `REA could not resolve the latest release: ${failure.detail}. Retry rea update when registry access is available.`;
         case "invalid-metadata":
@@ -44,6 +46,33 @@ const versionCheckRemediation = (release) => {
 };
 /** Identify, resolve, install, and verify REA without applying setup changes. */
 export const runUpdate = async (currentVersion, host, output = "human") => {
+    let result;
+    let primaryFailure;
+    let failed = false;
+    try {
+        result = await runUpdateWorkflow(currentVersion, host, output);
+    }
+    catch (cause) {
+        failed = true;
+        primaryFailure = cause;
+    }
+    let cleanupFailure;
+    try {
+        cleanupFailure = await host.close?.();
+    }
+    catch (cause) {
+        cleanupFailure = `Update resource cleanup failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+    }
+    if (failed) {
+        if (cleanupFailure !== undefined)
+            throw new AggregateError([primaryFailure, new Error(cleanupFailure)], "Update failed and its resource cleanup remains incomplete.", { cause: primaryFailure });
+        throw primaryFailure;
+    }
+    if (result === undefined)
+        throw new Error("Update result was not produced.");
+    return cleanupFailure === undefined ? result : { ...result, cleanupFailure };
+};
+const runUpdateWorkflow = async (currentVersion, host, output) => {
     const installation = await host.installation();
     const release = await host.latestVersion(installation);
     const latestVersion = release.ok ? release.value : null;
@@ -61,7 +90,7 @@ export const runUpdate = async (currentVersion, host, output = "human") => {
             status: "current",
             currentVersion,
             latestVersion: targetVersion,
-            installMethod: installation === undefined ? "unknown" : "npm",
+            installMethod: installation?.manager ?? "unknown",
         };
     if (installation === undefined)
         return {
@@ -78,7 +107,7 @@ export const runUpdate = async (currentVersion, host, output = "human") => {
             currentVersion,
             latestVersion: targetVersion,
             reason: "install",
-            remediation: `REA could not install ${targetVersion} in ${installation.prefix}: ${installed.error}. Repair this npm installation, then rerun rea update.`,
+            remediation: `REA could not install ${targetVersion} in ${installation.manager === "npm" ? installation.prefix : installation.globalDirectory}: ${installed.error}. Repair this ${installation.manager} installation, then rerun rea update.`,
         };
     const verified = await host.installedVersion(installation);
     if (!verified.ok || verified.value !== targetVersion)
@@ -88,7 +117,7 @@ export const runUpdate = async (currentVersion, host, output = "human") => {
             latestVersion: targetVersion,
             reason: "verification",
             ...(verified.ok ? { installedVersion: verified.value } : {}),
-            remediation: `npm completed, but REA could not verify ${targetVersion} in ${installation.packageRoot}: ${verified.ok ? `the executable reported ${verified.value}` : verified.error}. The installation may have changed; repair it before retrying.`,
+            remediation: `${installation.manager} completed, but REA could not verify ${targetVersion} in ${installation.packageRoot}: ${verified.ok ? `the executable reported ${verified.value}` : verified.error}. The installation may have changed; repair it before retrying.`,
         };
     const maintenance = await host.planMaintenance(installation);
     return {
@@ -96,7 +125,7 @@ export const runUpdate = async (currentVersion, host, output = "human") => {
         previousVersion: currentVersion,
         latestVersion: targetVersion,
         installedVersion: verified.value,
-        installMethod: "npm",
+        installMethod: installation.manager,
         command: updateInstallCommand(installation, targetVersion),
         maintenance,
         remediation: maintenance.status === "planned"

package/dist/application/UpdateCommandProgress.js

@@ -0,0 +1,66 @@
+import { Writable } from "node:stream";
+import { finished } from "node:stream/promises";
+/** Borrow a progress destination while owning backpressure and write acknowledgements. */
+export class UpdateCommandProgress {
+    destination;
+    #streams = [];
+    #sink;
+    #finished;
+    #closing;
+    #failed = false;
+    #pendingWrites = 0;
+    #closed = false;
+    #onDestinationError = (cause) => {
+        this.#sink.destroy(cause);
+    };
+    constructor(destination) {
+        this.destination = destination;
+        this.#sink = new Writable({
+            write: (chunk, encoding, callback) => {
+                this.#pendingWrites++;
+                destination.write(chunk, encoding, (cause) => {
+                    this.#pendingWrites--;
+                    callback(cause);
+                    // A destination can emit its write error after invoking the callback.
+                    setImmediate(() => this.#releaseDestination());
+                });
+            },
+        });
+        this.#finished = finished(this.#sink, { cleanup: true }).then(() => undefined, (cause) => {
+            this.#failed = true;
+            for (const stream of this.#streams) {
+                stream.unpipe(this.#sink);
+                stream.resume();
+            }
+            return cause instanceof Error ? cause : new Error(String(cause));
+        });
+        destination.on("error", this.#onDestinationError);
+    }
+    pipe(stream) {
+        this.#streams.push(stream);
+        if (this.#failed)
+            stream.resume();
+        else
+            stream.pipe(this.#sink, { end: false });
+    }
+    close() {
+        this.#closing ??= this.#close();
+        return this.#closing;
+    }
+    async #close() {
+        for (const stream of this.#streams)
+            stream.unpipe(this.#sink);
+        this.#sink.end();
+        try {
+            return await this.#finished;
+        }
+        finally {
+            this.#closed = true;
+            setImmediate(() => this.#releaseDestination());
+        }
+    }
+    #releaseDestination() {
+        if (this.#closed && this.#pendingWrites === 0)
+            this.destination.off("error", this.#onDestinationError);
+    }
+}

package/dist/application/UpdateFailure.js

@@ -0,0 +1,17 @@
+/** Whether the update command left the requested release unapplied. */
+export const isUpdateFailure = (result) => {
+    if (result.cleanupFailure !== undefined)
+        return true;
+    const status = result.status;
+    switch (status) {
+        case "current":
+        case "updated":
+            return false;
+        case "failed":
+            return true;
+        default: {
+            const exhaustive = status;
+            throw new TypeError(`Unhandled update result status: ${String(exhaustive)}`);
+        }
+    }
+};

package/dist/application/UpdateMaintenance.js

@@ -1,11 +1,8 @@
 import { z } from "zod";
-import { PRODUCT_IDENTITY } from "../identity.js";
-import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
-import { readClientRegistrationStatuses } from "./ClientRegistrationStatus.js";
-import { clientServerForcedEnabled, clientServerListedDisabled, effectiveClientServer, parseClientConfiguration, } from "./ClientConfigurationDocument.js";
-import { supportedClients } from "./SupportedClients.js";
+import { RegularFileCleanupFailure } from "./RegularFileRead.js";
+import { classifyClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
+import { readClientRegistrationInspections } from "./ClientRegistrationStatus.js";
 import { existingSkillDestinations } from "./SetupSkill.js";
-import { readRegularFileText } from "./RegularFileRead.js";
 const setupPlanSchema = z.object({
     status: z.literal("planned"),
     plannedActions: z.array(z.object({
@@ -21,34 +18,21 @@ const setupPlanSchema = z.object({
     })),
 });
 /** Discover owned registrations and REA skills without writes. */
-export const existingMaintenanceScope = async (home, entryPoint, environment) => {
-    const registrations = await readClientRegistrationStatuses(home, entryPoint, {
+export const existingMaintenanceScope = async (home, entryPoint, environment, resources) => {
+    const registrations = await readClientRegistrationInspections(home, entryPoint, {
         environment,
+        ...(resources === undefined ? {} : { resources }),
     });
-    const supported = supportedClients(home, process.platform, environment);
     const clients = [];
-    for (const registration of registrations) {
-        if ((registration.state !== "aligned" && registration.state !== "stale") ||
-            !isOwnedClientRegistrationCommand(registration.command, entryPoint))
+    for (const { status: registration, activation } of registrations) {
+        if (activation !== "enabled" ||
+            (registration.state !== "aligned" && registration.state !== "stale") ||
+            classifyClientRegistrationCommand(registration.command, entryPoint) !==
+                "owned")
             continue;
-        const client = supported.find(({ name }) => name === registration.client);
-        if (client === undefined)
-            continue;
-        const parsed = parseClientConfiguration(await readRegularFileText(client.configPath), client.format);
-        const enabled = z
-            .object({
-            enabled: z.boolean().optional(),
-            disabled: z.boolean().optional(),
-        })
-            .parse(effectiveClientServer(parsed, PRODUCT_IDENTITY.mcpServerKey));
-        // Root disable lists override enabled entries and OMP's force-on allowlist.
-        if ((enabled.enabled !== false ||
-            clientServerForcedEnabled(parsed, PRODUCT_IDENTITY.mcpServerKey)) &&
-            enabled.disabled !== true &&
-            !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey))
-            clients.push(client.name);
+        clients.push(registration.client);
     }
-    const skillDestinations = await existingSkillDestinations(home, environment);
+    const skillDestinations = await existingSkillDestinations(home, environment, process.platform, resources);
     return {
         clients,
         skill: skillDestinations.length > 0,
@@ -56,9 +40,9 @@ export const existingMaintenanceScope = async (home, entryPoint, environment) =>
     };
 };
 /** Ask the verified new executable to plan only existing REA integrations. */
-export const planIntegrationMaintenance = async (home, entryPoint, environment, execute) => {
+export const planIntegrationMaintenance = async (home, entryPoint, environment, execute, resources) => {
     try {
-        const scope = await existingMaintenanceScope(home, entryPoint, environment);
+        const scope = await existingMaintenanceScope(home, entryPoint, environment, resources);
         const skillDestinations = scope.skillDestinations ?? [];
         if (scope.clients.length === 0 && !scope.skill)
             return { status: "current", plannedActions: [] };
@@ -102,6 +86,9 @@ export const planIntegrationMaintenance = async (home, entryPoint, environment,
         };
     }
     catch (cause) {
+        // Without a supplied scope, the typed failure is the caller's cleanup capability.
+        if (resources === undefined && cause instanceof RegularFileCleanupFailure)
+            throw cause;
         return {
             status: "unavailable",
             remediation: cause instanceof Error ? cause.message : String(cause),

package/dist/application/UpdateRuntime.js

@@ -1,51 +1,84 @@
-import { realpath } from "node:fs/promises";
+import { realpath, stat } from "node:fs/promises";
 import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import spawn from "cross-spawn";
+import { ProviderProcessSupervisor } from "../process/ProviderProcess.js";
+import { UpdateCommandProgress } from "./UpdateCommandProgress.js";
+import { lt, valid } from "semver";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
 import { err, ok } from "../domain/result.js";
 import { safeParseJson } from "../domain/safeJson.js";
 import { updateInstallCommand, } from "./Update.js";
 import { planIntegrationMaintenance } from "./UpdateMaintenance.js";
-/** Run an updater subprocess with complete diagnostics and isolated machine output. */
-export const runUpdateCommand = (command, selectedEnvironment, output = "structured") => new Promise((resolveResult) => {
+import { withoutPackageRunnerIdentity } from "./ClientRegistrationIdentity.js";
+/** Aggregate raw-byte retention policy for package-manager replies and diagnostics. */
+export const UPDATE_COMMAND_OUTPUT_BYTES = 4 * 1024 * 1024;
+/** Complete metadata queries share launch and collection with diagnostic-only installs. */
+export const runUpdateCommand = (command, selectedEnvironment, output = "structured", workingDirectory = undefined) => runUpdateProcess(command, selectedEnvironment, output, workingDirectory, "complete");
+const runUpdateProcess = async (command, selectedEnvironment, output, workingDirectory, retention) => {
     const [executable, ...args] = command;
-    if (executable === undefined) {
-        resolveResult(err("No executable supplied."));
-        return;
-    }
-    const environment = { ...selectedEnvironment };
-    // A fresh installed entry point must not inherit npx's invocation identity.
-    delete environment.npm_command;
+    if (executable === undefined)
+        return err("No executable supplied.");
+    const environment = withoutPackageRunnerIdentity(selectedEnvironment);
     const child = spawn(executable, args, {
         stdio: ["ignore", "pipe", "pipe"],
         env: environment,
         windowsHide: true,
+        ...(workingDirectory === undefined ? {} : { cwd: workingDirectory }),
     });
-    let stdout = "";
-    let stderr = "";
-    child.stdout?.setEncoding("utf8");
-    child.stderr?.setEncoding("utf8");
-    child.stdout?.on("data", (chunk) => {
-        stdout += chunk;
-        if (output === "human")
-            process.stderr.write(chunk);
-    });
-    child.stderr?.on("data", (chunk) => {
-        stderr += chunk;
-        if (output === "human")
-            process.stderr.write(chunk);
+    let processFailure;
+    const supervisor = new ProviderProcessSupervisor({ process: child, ownsProcessLifetime: true }, {
+        maxDiagnosticBytes: UPDATE_COMMAND_OUTPUT_BYTES,
+        onDiagnostic: (event) => {
+            if (event.type === "error")
+                processFailure ??= event.message;
+        },
     });
-    child.once("error", (cause) => resolveResult(err(cause.message)));
-    child.once("close", (code, signal) => resolveResult(code === 0
-        ? ok(stdout.trim())
-        : err(stderr.trim() ||
-            stdout.trim() ||
-            (signal === null
-                ? `Process exited with code ${String(code)}.`
-                : `Process terminated by ${signal}.`))));
-});
+    const progress = output === "human" ? new UpdateCommandProgress(process.stderr) : undefined;
+    if (progress !== undefined) {
+        for (const stream of [child.stdout, child.stderr])
+            if (stream !== null)
+                progress.pipe(stream);
+    }
+    try {
+        // Drain even an oversized reply. Verbosity must not interrupt a package install.
+        // Keep the existing launch/signal policy; this collector owns no process-tree authority.
+        await supervisor.waitForOutputClose();
+        const progressFailure = await progress?.close();
+        const snapshot = supervisor.snapshot();
+        if (processFailure !== undefined)
+            return err(processFailure);
+        if (snapshot.outputIncomplete === true)
+            return err("Update command output did not close completely.");
+        if (retention === "complete" && snapshot.diagnosticTruncated === true)
+            return err(`Update command output exceeded the ${UPDATE_COMMAND_OUTPUT_BYTES}-byte complete-output retention budget; reply was not accepted.`);
+        if (snapshot.exitCode !== 0 || snapshot.signal !== null) {
+            const detail = snapshot.stderr.text.trim() ||
+                snapshot.stdout.text.trim() ||
+                (typeof snapshot.signal === "string"
+                    ? `Process terminated by ${snapshot.signal}.`
+                    : typeof snapshot.exitCode === "number"
+                        ? `Process exited with code ${snapshot.exitCode}.`
+                        : "Update command failed without a recorded exit status.");
+            return err(snapshot.diagnosticTruncated
+                ? `${detail}\n[Update diagnostics truncated at ${UPDATE_COMMAND_OUTPUT_BYTES} bytes; later output omitted.]`
+                : detail);
+        }
+        if (retention === "complete" &&
+            (snapshot.stdout.invalidUtf8 || snapshot.stderr.invalidUtf8))
+            return err("Update command returned invalid UTF-8; complete output is unavailable.");
+        if (progressFailure !== undefined)
+            return err(`Update progress output failed: ${progressFailure.message}`);
+        return ok(retention === "diagnostics" ? "" : snapshot.stdout.text.trim());
+    }
+    finally {
+        // Reached only after physical close; no child or inherited pipe remains pending.
+        supervisor.dispose();
+        await progress?.close();
+    }
+};
 const requireCommandOutput = async (command, environment) => {
     const result = await runUpdateCommand(command, environment);
     if (!result.ok)
@@ -70,7 +103,7 @@ export const detectNpmInstallation = async (packageRoot, host) => {
             const prefix = await host.globalPrefix();
             return prefix.length === 0
                 ? undefined
-                : { prefix, packageRoot: canonicalPackageRoot };
+                : { manager: "npm", prefix, packageRoot: canonicalPackageRoot };
         }
     }
     catch (cause) {
@@ -83,9 +116,64 @@ export const detectNpmInstallation = async (packageRoot, host) => {
         basename(nodeModules) !== "node_modules" ||
         basename(library) !== "lib")
         return undefined;
-    return { prefix: dirname(library), packageRoot: canonicalPackageRoot };
+    return {
+        manager: "npm",
+        prefix: dirname(library),
+        packageRoot: canonicalPackageRoot,
+    };
+};
+const nonemptyEnvironment = (value) => value === undefined || value.length === 0 ? undefined : value;
+/**
+ * Bun's global project directory for the selected environment, in Bun's precedence:
+ * BUN_INSTALL_GLOBAL_DIR, then $BUN_INSTALL/install/global, then
+ * $XDG_CACHE_HOME/.bun/install/global, then ~/.bun/install/global.
+ * Resolve against the caller's cwd before reusing the path as a subprocess cwd.
+ */
+export const bunGlobalDirectory = (environment, platform) => {
+    const explicit = nonemptyEnvironment(environment.BUN_INSTALL_GLOBAL_DIR);
+    if (explicit !== undefined)
+        return resolve(explicit);
+    const installRoot = nonemptyEnvironment(environment.BUN_INSTALL);
+    if (installRoot !== undefined)
+        return resolve(installRoot, "install", "global");
+    const cacheRoot = nonemptyEnvironment(environment.XDG_CACHE_HOME) ??
+        homeDirectoryFromEnvironment(environment, platform);
+    return resolve(cacheRoot, ".bun", "install", "global");
+};
+/**
+ * Identify the running package as Bun's global installation.
+ * Bun walks up to an ancestor project when its global directory has no
+ * package.json, so the global manifest must exist before `bun add --global`
+ * can be trusted to update this package root.
+ */
+export const detectBunInstallation = async (packageRoot, globalDirectory, host) => {
+    try {
+        const canonicalPackageRoot = await host.canonicalPath(packageRoot);
+        const globalPackageRoot = await host.canonicalPath(join(globalDirectory, "node_modules", PRODUCT_IDENTITY.packageName));
+        if (canonicalPackageRoot !== globalPackageRoot ||
+            !(await host.isFile(join(globalDirectory, "package.json"))))
+            return undefined;
+        return {
+            manager: "bun",
+            globalDirectory,
+            packageRoot: canonicalPackageRoot,
+        };
+    }
+    catch (cause) {
+        // best-effort cleanup: optional install-location probing; unknown means not Bun-managed.
+        void cause;
+        return undefined;
+    }
 };
 const INVALID_NPM_RELEASE_METADATA = "Invalid npm release metadata: expected a version string or a single-element version array.";
+/** bun info arguments for dist-tags.latest; Bun resolves its configured registry. */
+export const BUN_LATEST_VERSION_COMMAND = [
+    "bun",
+    "info",
+    PRODUCT_IDENTITY.packageName,
+    "dist-tags.latest",
+    "--json",
+];
 /** npm view arguments for dist-tags.latest, scoped to the owning prefix when known. */
 export const npmLatestVersionCommand = (installation) => [
     "npm",
@@ -120,7 +208,7 @@ const readNpmLatestVersion = (value) => {
     return typeof only === "string" ? nonemptyVersion(only) : undefined;
 };
 const nonemptyVersion = (value) => value.length === 0 ? undefined : value;
-/** Classify npm view output as a version or a lookup failure. */
+/** Classify `npm view` or `bun info` output as a version or a lookup failure. */
 export const npmReleaseLookup = (response) => {
     if (!response.ok)
         return err({ kind: "unavailable", detail: response.error });
@@ -129,22 +217,78 @@ export const npmReleaseLookup = (response) => {
         ? ok(parsed.value)
         : err({ kind: "invalid-metadata", detail: parsed.error });
 };
-/** Create npm, registry, verification, and read-only maintenance effects. */
-export const systemUpdateHost = (packageRoot = fileURLToPath(new URL("../..", import.meta.url)), home = undefined, environment = process.env) => ({
-    installation: () => detectNpmInstallation(packageRoot, {
-        canonicalPath: realpath,
-        globalRoot: () => requireCommandOutput(["npm", "root", "--global"], environment),
-        globalPrefix: () => requireCommandOutput(["npm", "prefix", "--global"], environment),
-    }),
-    latestVersion: async (installation) => npmReleaseLookup(await runUpdateCommand(npmLatestVersionCommand(installation), environment)),
-    installVersion: async (installation, version, output) => {
-        const result = await runUpdateCommand(updateInstallCommand(installation, version), environment, output);
-        return result.ok ? ok(undefined) : result;
-    },
-    installedVersion: (installation) => runUpdateCommand([
-        process.execPath,
-        join(installation.packageRoot, "scripts", "rea.mjs"),
-        "--version",
-    ], environment),
-    planMaintenance: (installation) => planIntegrationMaintenance(home ?? homeDirectoryFromEnvironment(environment, process.platform), join(installation.packageRoot, "scripts", "rea.mjs"), environment, (command) => runUpdateCommand(command, environment)),
-});
+const isFile = async (path) => {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (cause) {
+        // best-effort cleanup: a missing or unreadable manifest is not an owned Bun global project.
+        void cause;
+        return false;
+    }
+};
+/**
+ * Environment and working directory for package-manager subprocesses.
+ * Bun commands run inside the identified global project with that directory
+ * pinned, so the caller's current project and Bun's ancestor search are never
+ * selected. npm keeps the caller's working directory; its prefix is explicit.
+ */
+const packageManagerContext = (installation, environment) => installation?.manager === "bun"
+    ? {
+        environment: {
+            ...environment,
+            BUN_INSTALL_GLOBAL_DIR: installation.globalDirectory,
+        },
+        workingDirectory: installation.globalDirectory,
+    }
+    : { environment, workingDirectory: undefined };
+/** Create package-manager, registry, verification, and read-only maintenance effects. */
+export const systemUpdateHost = (packageRoot = fileURLToPath(new URL("../..", import.meta.url)), home = undefined, environment = process.env) => {
+    const resources = new ArtifactResourceScope();
+    return {
+        installation: async () => (await detectBunInstallation(packageRoot, bunGlobalDirectory(environment, process.platform), { canonicalPath: realpath, isFile })) ??
+            detectNpmInstallation(packageRoot, {
+                canonicalPath: realpath,
+                globalRoot: () => requireCommandOutput(["npm", "root", "--global"], environment),
+                globalPrefix: () => requireCommandOutput(["npm", "prefix", "--global"], environment),
+            }),
+        latestVersion: async (installation) => {
+            const context = packageManagerContext(installation, environment);
+            if (installation?.manager === "bun") {
+                const version = await runUpdateCommand(["bun", "--version"], context.environment, "structured", context.workingDirectory);
+                if (!version.ok)
+                    return err({ kind: "unavailable", detail: version.error });
+                const bunVersion = valid(version.value);
+                // bun info was introduced in 1.2.17; older releases reserve the command.
+                if (bunVersion === null || lt(bunVersion, "1.2.17"))
+                    return err({
+                        kind: "unsupported-package-manager",
+                        detail: `REA updates for Bun global installations require Bun 1.2.17 or later; bun --version returned ${JSON.stringify(version.value)}. Upgrade Bun manually, then rerun rea update.`,
+                    });
+            }
+            return npmReleaseLookup(await runUpdateCommand(installation?.manager === "bun"
+                ? BUN_LATEST_VERSION_COMMAND
+                : npmLatestVersionCommand(installation), context.environment, "structured", context.workingDirectory));
+        },
+        installVersion: async (installation, version, output) => {
+            const context = packageManagerContext(installation, environment);
+            const result = await runUpdateProcess(updateInstallCommand(installation, version), context.environment, output, context.workingDirectory, "diagnostics");
+            return result.ok ? ok(undefined) : result;
+        },
+        installedVersion: (installation) => runUpdateCommand([
+            process.execPath,
+            join(installation.packageRoot, "scripts", "rea.mjs"),
+            "--version",
+        ], environment),
+        planMaintenance: (installation) => planIntegrationMaintenance(home ?? homeDirectoryFromEnvironment(environment, process.platform), join(installation.packageRoot, "scripts", "rea.mjs"), environment, (command) => runUpdateCommand(command, environment), resources),
+        close: async () => {
+            try {
+                await resources.close();
+                return undefined;
+            }
+            catch (cause) {
+                return `Update resource cleanup failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+            }
+        },
+    };
+};