rea-agents 6.4.0 → 6.5.0

package/dist/application/JsonInputFile.js

@@ -1,8 +1,12 @@
 import { constants } from "node:buffer";
+import { createHash } from "node:crypto";
 import { pipeline } from "node:stream/promises";
 import { getHeapStatistics } from "node:v8";
+import { asStream, none } from "stream-chain";
+import fun from "stream-chain/fun.js";
 import parser from "stream-json/parser.js";
 import streamValues from "stream-json/streamers/stream-values.js";
+import streamArray from "stream-json/streamers/stream-array.js";
 import { RegularFileChangedError } from "../filesystem/RegularFile.js";
 import { withRegularFile } from "./RegularFileRead.js";
 import { JSON_BYTE_ORDER_MARK_MESSAGE, JSON_INPUT_RESOURCE_REMEDIATION, parseUtf8Json, } from "./Utf8JsonInput.js";
@@ -20,77 +24,216 @@ const nativeParseFits = (inputBytes) => inputBytes <= NATIVE_PARSE_READ_BUDGET &
     // whose individual container allocations cannot be intercepted.
     inputBytes * 72 + READ_CHUNK_BYTES <=
         getHeapStatistics().total_available_size;
+/** Scan selected members without retaining skipped subtrees or prior array items. */
+export const readJsonObjectFile = (path, operation, scans, signal, resources) => withRegularFile(path, async (handle, stats) => {
+    let previousDigest;
+    try {
+        const native = await readNativeJson(handle, stats.size, path, operation, signal);
+        if (native !== undefined) {
+            if (!native.ok)
+                return native;
+            const value = native.value;
+            if (typeof value !== "object" ||
+                value === null ||
+                Array.isArray(value))
+                return err(invalidJson(operation, "JSON document root must be an object"));
+            for (const members of scans)
+                for (const [key, member] of members) {
+                    if (!Object.hasOwn(value, key))
+                        continue;
+                    signal?.throwIfAborted();
+                    member.begin();
+                    const selected = Reflect.get(value, key);
+                    if (member.mode === "array" && !Array.isArray(selected)) {
+                        member.reject(new TypeError(`JSON member ${key} must be an array`));
+                        continue;
+                    }
+                    for (const item of member.mode === "array" &&
+                        Array.isArray(selected)
+                        ? selected
+                        : [selected]) {
+                        signal?.throwIfAborted();
+                        try {
+                            await member.accept(item);
+                        }
+                        catch (cause) {
+                            member.reject(cause);
+                        }
+                    }
+                }
+            return ok(undefined);
+        }
+        for (const members of scans) {
+            const hash = createHash("sha256");
+            let rootObject = false;
+            let depth = 0;
+            let key;
+            let consume;
+            await pipeline(decodedChunks(handle, stats.size, path, signal, (bytes) => {
+                hash.update(bytes);
+            }), asStream(fun(parser({
+                jsonStreaming: false,
+                streamValues: false,
+                packKeys: false,
+                packStrings: false,
+                packNumbers: false,
+            }), packJsonScalars(operation, stats.size, path), (token) => {
+                const opens = token.name === "startObject" || token.name === "startArray";
+                const closes = token.name === "endObject" || token.name === "endArray";
+                if (depth === 0) {
+                    rootObject = token.name === "startObject";
+                }
+                else if (rootObject &&
+                    depth === 1 &&
+                    token.name === "keyValue") {
+                    key = token.value;
+                }
+                else if (rootObject && depth === 1 && !closes) {
+                    const member = key === undefined ? undefined : members.get(key);
+                    consume = undefined;
+                    if (member !== undefined) {
+                        member.begin();
+                        if (member.mode === "array" &&
+                            token.name !== "startArray") {
+                            member.reject(new TypeError(`JSON member ${key} must be an array`));
+                        }
+                        else {
+                            consume = memberConsumer(member, operation, stats.size, path);
+                        }
+                    }
+                    key = undefined;
+                }
+                const selected = consume;
+                if (opens)
+                    depth += 1;
+                if (closes)
+                    depth -= 1;
+                if (rootObject && depth === 1 && token.name !== "keyValue")
+                    consume = undefined;
+                if (selected === undefined)
+                    return none;
+                return selected(token);
+            })), signal === undefined ? {} : { signal });
+            if (!rootObject)
+                return err(invalidJson(operation, "JSON document root must be an object"));
+            const digest = hash.digest("hex");
+            if (previousDigest !== undefined && digest !== previousDigest)
+                throw new RegularFileChangedError(path);
+            previousDigest = digest;
+        }
+        return ok(undefined);
+    }
+    catch (cause) {
+        const failure = jsonReadFailure(cause, operation, stats.size, path);
+        if (failure !== undefined)
+            return err(failure);
+        throw cause;
+    }
+}, {
+    signal,
+    ...(resources === undefined ? {} : { resources }),
+});
+const memberConsumer = (member, operation, size, path) => {
+    let admit = admitJsonAssembly(operation, size, path);
+    const streamer = member.mode === "array" ? streamArray() : streamValues();
+    const consume = fun((token) => admit(token), streamer, (row) => {
+        if (typeof row !== "object" || row === null || !("value" in row))
+            throw new Error("Unexpected JSON member parser result");
+        // The preceding array item has left the assembler; retain only what the
+        // consumer owns and use live headroom when admitting the next item.
+        admit = admitJsonAssembly(operation, size, path);
+        try {
+            const accepted = member.accept(row.value);
+            if (accepted instanceof Promise)
+                return accepted.then(() => none, (cause) => {
+                    member.reject(cause);
+                    return none;
+                });
+        }
+        catch (cause) {
+            member.reject(cause);
+        }
+        return none;
+    });
+    return (token) => {
+        const consumed = consume(token);
+        return consumed instanceof Promise ? consumed.then(() => none) : none;
+    };
+};
 /** Parse strict UTF-8 JSON without requiring a whole-document string. */
-export const readJsonInputFile = (path, operation, signal) => withRegularFile(path, async (handle, stats) => {
+export const readJsonInputFile = (path, operation, signal, resources) => withRegularFile(path, async (handle, stats) => {
     let found = false;
     let value;
     try {
-        const prefix = nativeParseFits(stats.size)
-            ? await readPrefix(handle, stats.size + 1, signal)
-            : undefined;
-        if (prefix !== undefined) {
-            if (!prefix.complete || prefix.bytes.length !== stats.size)
-                throw new RegularFileChangedError(path);
-            const parsed = parseUtf8Json(prefix.bytes, operation, path, "json-file-input");
-            return parsed.ok
-                ? ok(parsed.value)
-                : err(invalidJson(operation, parsed.error, parsed.cause));
-        }
-        await pipeline(decodedChunks(handle, stats.size, path, signal), parser.asStream({
+        const native = await readNativeJson(handle, stats.size, path, operation, signal);
+        if (native !== undefined)
+            return native;
+        await pipeline(decodedChunks(handle, stats.size, path, signal), 
+        // Fuse synchronous token stages so only file chunks cross the async
+        // stream boundary. Admission still precedes scalar/value assembly.
+        asStream(fun(parser({
             jsonStreaming: false,
             streamValues: false,
             packKeys: false,
             packStrings: false,
             packNumbers: false,
-        }), packJsonScalars(operation, stats.size, path), admitJsonAssembly(operation, stats.size, path), streamValues.asStream(), async (rows) => {
-            for await (const row of rows) {
-                if (found ||
-                    typeof row !== "object" ||
-                    row === null ||
-                    !("key" in row) ||
-                    row.key !== 0 ||
-                    !("value" in row))
-                    throw new Error("Unexpected JSON parser result");
-                found = true;
-                value = row.value;
-            }
-        }, signal === undefined ? {} : { signal });
+        }), packJsonScalars(operation, stats.size, path), admitJsonAssembly(operation, stats.size, path), streamValues(), (row) => {
+            if (found ||
+                typeof row !== "object" ||
+                row === null ||
+                !("key" in row) ||
+                row.key !== 0 ||
+                !("value" in row))
+                throw new Error("Unexpected JSON parser result");
+            found = true;
+            value = row.value;
+            return none;
+        })), signal === undefined ? {} : { signal });
         return found
             ? ok(value)
             : err(invalidJson(operation, "JSON document is empty"));
     }
     catch (cause) {
-        if (cause instanceof AnalysisResourceConstraintError)
-            return err(cause);
-        if (cause instanceof TypeError &&
-            "code" in cause &&
-            cause.code === "ERR_ENCODING_INVALID_ENCODED_DATA")
-            return err(invalidJson(operation, "JSON input is not valid UTF-8", cause));
-        if (cause instanceof SyntaxError ||
-            (cause instanceof Error && cause.message.startsWith("Parser ")))
-            return err(invalidJson(operation, cause.message, cause));
-        if (cause instanceof Error &&
-            ((cause instanceof RangeError &&
-                cause.message === "Invalid string length") ||
-                ("code" in cause && cause.code === "ERR_STRING_TOO_LONG")))
-            return err(new AnalysisResourceConstraintError(operation, "memory", "An individual JSON string or number token exceeds the runtime string limit", {
-                input_path: path,
-                input_file_bytes: stats.size,
-                max_string_code_units: constants.MAX_STRING_LENGTH,
-            }, {
-                cause,
-                remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
-            }));
+        const failure = jsonReadFailure(cause, operation, stats.size, path);
+        if (failure !== undefined)
+            return err(failure);
         throw cause;
     }
-}, { signal });
-const packJsonScalars = (operation, inputFileBytes, path) => async function* (tokens) {
+}, {
+    signal,
+    ...(resources === undefined ? {} : { resources }),
+});
+const jsonReadFailure = (cause, operation, size, path) => {
+    if (cause instanceof AnalysisResourceConstraintError)
+        return cause;
+    if (cause instanceof TypeError &&
+        "code" in cause &&
+        cause.code === "ERR_ENCODING_INVALID_ENCODED_DATA")
+        return invalidJson(operation, "JSON input is not valid UTF-8", cause);
+    if (cause instanceof SyntaxError ||
+        (cause instanceof Error && cause.message.startsWith("Parser ")))
+        return invalidJson(operation, cause.message, cause);
+    if (cause instanceof Error &&
+        ((cause instanceof RangeError &&
+            cause.message === "Invalid string length") ||
+            ("code" in cause && cause.code === "ERR_STRING_TOO_LONG")))
+        return new AnalysisResourceConstraintError(operation, "memory", "An individual JSON string or number token exceeds the runtime string limit", {
+            input_path: path,
+            input_file_bytes: size,
+            max_string_code_units: constants.MAX_STRING_LENGTH,
+        }, {
+            cause,
+            remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
+        });
+    return undefined;
+};
+const packJsonScalars = (operation, inputFileBytes, path) => {
     let kind;
     let length = 0;
     let value = "";
     let parts = [];
     let partLength = 0;
-    for await (const token of tokens) {
+    return (token) => {
         if (typeof token !== "object" || token === null || !("name" in token))
             throw new Error("Unexpected JSON parser token");
         switch (token.name) {
@@ -124,27 +267,29 @@ const packJsonScalars = (operation, inputFileBytes, path) => async function* (to
                 break;
             case "endKey":
             case "endString":
-            case "endNumber":
+            case "endNumber": {
                 if (kind === undefined)
                     throw new Error("Unexpected JSON scalar end");
                 requireStringAssemblyHeadroom(operation, inputFileBytes, path, length);
-                yield { name: kind, value: value + parts.join("") };
+                const packed = { name: kind, value: value + parts.join("") };
                 kind = undefined;
                 length = 0;
                 value = "";
                 parts = [];
                 partLength = 0;
-                break;
+                return packed;
+            }
             default:
-                yield token;
+                return token;
         }
-    }
+        return none;
+    };
 };
 /** Admit the retained value graph before the upstream assembler grows it. */
-const admitJsonAssembly = (operation, inputFileBytes, path) => async function* (tokens) {
+const admitJsonAssembly = (operation, inputFileBytes, path) => {
     let projectedBytes = 0;
     let nextCheck = 0;
-    for await (const token of tokens) {
+    return (token) => {
         if (typeof token !== "object" || token === null || !("name" in token))
             throw new Error("Unexpected JSON assembly token");
         if (token.name === "startObject" || token.name === "startArray") {
@@ -179,8 +324,8 @@ const admitJsonAssembly = (operation, inputFileBytes, path) => async function* (
                 }, { remediationAction: JSON_INPUT_RESOURCE_REMEDIATION });
             nextCheck = projectedBytes + READ_CHUNK_BYTES;
         }
-        yield token;
-    }
+        return token;
+    };
 };
 const requireStringAssemblyHeadroom = (operation, inputFileBytes, path, stringCodeUnits) => {
     if (stringCodeUnits < PACKED_TOKEN_PART_CODE_UNITS)
@@ -201,7 +346,7 @@ const requireStringAssemblyHeadroom = (operation, inputFileBytes, path, stringCo
             remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
         });
 };
-async function* decodedChunks(handle, admittedBytes, path, signal) {
+async function* decodedChunks(handle, admittedBytes, path, signal, observe) {
     const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
     let leading = true;
     const checked = (text) => {
@@ -216,14 +361,16 @@ async function* decodedChunks(handle, admittedBytes, path, signal) {
     let observedBytes = 0;
     while (true) {
         signal?.throwIfAborted();
-        const read = await handle.read(bytes, 0, Math.min(bytes.length, admittedBytes - observedBytes + 1), null);
+        const read = await handle.read(bytes, 0, Math.min(bytes.length, admittedBytes - observedBytes + 1), observedBytes);
         signal?.throwIfAborted();
         if (read.bytesRead === 0)
             break;
         observedBytes += read.bytesRead;
         if (observedBytes > admittedBytes)
             throw new RegularFileChangedError(path);
-        yield checked(decoder.decode(bytes.subarray(0, read.bytesRead), { stream: true }));
+        const chunk = bytes.subarray(0, read.bytesRead);
+        observe?.(chunk);
+        yield checked(decoder.decode(chunk, { stream: true }));
     }
     if (observedBytes !== admittedBytes)
         throw new RegularFileChangedError(path);
@@ -249,4 +396,15 @@ const readPrefix = async (handle, size, signal) => {
     // One byte beyond the admitted extent proves the selected file changed.
     return { bytes, complete: false };
 };
+const readNativeJson = async (handle, size, path, operation, signal) => {
+    if (!nativeParseFits(size))
+        return undefined;
+    const prefix = await readPrefix(handle, size + 1, signal);
+    if (!prefix.complete || prefix.bytes.length !== size)
+        throw new RegularFileChangedError(path);
+    const parsed = parseUtf8Json(prefix.bytes, operation, path, "json-file-input");
+    return parsed.ok
+        ? ok(parsed.value)
+        : err(invalidJson(operation, parsed.error, parsed.cause));
+};
 const invalidJson = (operation, message, cause) => new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, [{ path: [], reason: "invalid_format", expected: "JSON", message }]);

package/dist/application/LinuxHopper.js

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto";
-import { execFile } from "node:child_process";
 import { createReadStream } from "node:fs";
 import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { promisify } from "node:util";
+import { execFileBoundedOutput } from "../process/ExecFileBoundedOutput.js";
 import { execFileOutput } from "../process/ExecFileOutput.js";
 import { downloadHopperPackage, HOPPER_DOWNLOAD_BYTES, } from "./HopperDownload.js";
-const execFileAsync = promisify(execFile);
+/** Package-manager output retained per stream without stopping the command. */
+const PACKAGE_MANAGER_OUTPUT_BYTES = 64 * 1024;
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
 const SUPPORTED_HOPPER_SHA256 = new Set([
     "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded",
@@ -37,9 +37,37 @@ export const linuxHopperInstallDisclosure = (family, isRoot) => {
         downloadUrl: release.filename,
         expectedBytes: Number(release.file_length),
         expectedSha1: release.file_hash,
-        commands: linuxPackageManagerCommands(family, `<verified-hopper.${family}>`, isRoot).map(({ executable, args }) => `${executable} ${args.join(" ")}`),
+        commands: linuxPackageManagerCommands(family, `<verified-hopper.${family}>`, isRoot).map(({ executable, args }) => formatCommandForDisplay(executable, args)),
     };
 };
+/**
+ * Whether REA's analysis providers run on this distribution. A recognized
+ * package family means a glibc host with a known package layout, which is what
+ * the providers need; downloading and installing the official Hopper package
+ * additionally requires a distribution on its tested list.
+ */
+export const supportsReaHost = (distribution) => distribution?.packageFamily !== undefined;
+/** Own failed temporary cleanup until a later retry succeeds. */
+export class LinuxHopperTemporaryCleanupOwner {
+    pending = new Map();
+    retain(failure) {
+        this.pending.set(failure.path, failure);
+    }
+    async retry(cleanup) {
+        const failures = [];
+        for (const path of this.pending.keys()) {
+            try {
+                await cleanup(path);
+                this.pending.delete(path);
+            }
+            catch (cause) {
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                failures.push(`Linux Hopper temporary cleanup failed for ${path}: ${reason}`);
+            }
+        }
+        return failures.length === 0 ? undefined : failures.join("; ");
+    }
+}
 /** Parse an os-release document without executing its shell syntax. */
 export const parseLinuxDistribution = (text) => {
     const fields = new Map();
@@ -51,15 +79,19 @@ export const parseLinuxDistribution = (text) => {
         const encoded = match[2];
         if (key === undefined || encoded === undefined)
             continue;
-        const value = encoded.startsWith('"') && encoded.endsWith('"')
-            ? encoded.slice(1, -1).replaceAll('\\"', '"').replaceAll("\\\\", "\\")
-            : encoded;
+        const quote = encoded[0];
+        const quoted = (quote === "'" || quote === '"') && encoded.endsWith(quote);
+        const value = !quoted
+            ? encoded
+            : quote === "'"
+                ? encoded.slice(1, -1)
+                : encoded.slice(1, -1).replace(/\\(["\\$`])/gu, "$1");
         fields.set(key, value);
     }
     const id = (fields.get("ID") ?? "unknown").toLowerCase();
     const versionId = fields.get("VERSION_ID");
     const packageFamily = packageFamilyFor(id, fields.get("ID_LIKE"));
-    const supported = packageFamily !== undefined &&
+    const hopperSetupSupported = packageFamily !== undefined &&
         (id === "arch" ||
             id === "cachyos" ||
             (id === "omarchy" && packageFamily === "arch") ||
@@ -70,9 +102,9 @@ export const parseLinuxDistribution = (text) => {
         id,
         ...(versionId === undefined ? {} : { versionId }),
     };
-    return supported
-        ? { ...identity, packageFamily, supported: true }
-        : { ...identity, packageFamily, supported: false };
+    return hopperSetupSupported
+        ? { ...identity, packageFamily, hopperSetupSupported: true }
+        : { ...identity, packageFamily, hopperSetupSupported: false };
 };
 /** Read and classify the current Linux distribution. */
 export const readLinuxDistribution = async () => {
@@ -90,42 +122,75 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(pro
     if (options.signal?.aborted === true)
         return { status: "failed", reason: "cancelled" };
     const distribution = await host.distribution();
-    if (distribution?.supported !== true)
+    if (distribution?.hopperSetupSupported !== true)
         return { status: "failed", reason: "unsupported_host" };
     let temporary;
+    let result;
     try {
-        const release = (options.releases ?? SUPPORTED_RELEASES)[distribution.packageFamily];
-        const archiveDownload = await host.download(release.filename, options);
-        if (!archiveDownload.ok)
-            return { status: "failed", reason: "download" };
-        if (!packageIntegrityMatches(archiveDownload.bytes, release))
-            return { status: "failed", reason: "integrity" };
-        temporary = await host.createTemporaryDirectory();
-        const archive = join(temporary, `hopper.${distribution.packageFamily}`);
-        await host.writeArchive(archive, archiveDownload.bytes);
-        if (!(await host.installPackage(distribution.packageFamily, archive)))
-            return { status: "failed", reason: "authorization_or_package_manager" };
-        const launcherPath = "/opt/hopper/bin/Hopper";
-        const launcherStatus = await host.launcherStatus(launcherPath);
-        if (launcherStatus !== "ready")
-            return {
-                status: "failed",
-                reason: launcherStatus === "missing" ? "launcher_missing" : launcherStatus,
-            };
-        return { status: "installed", launcherPath };
+        result = await (async () => {
+            const release = (options.releases ?? SUPPORTED_RELEASES)[distribution.packageFamily];
+            const archiveDownload = await host.download(release.filename, options);
+            if (!archiveDownload.ok)
+                return { status: "failed", reason: "download" };
+            if (!packageIntegrityMatches(archiveDownload.bytes, release))
+                return { status: "failed", reason: "integrity" };
+            temporary = await host.createTemporaryDirectory();
+            const archive = join(temporary, `hopper.${distribution.packageFamily}`);
+            await host.writeArchive(archive, archiveDownload.bytes);
+            const install = await host.installPackage(distribution.packageFamily, archive);
+            if (install.status === "failed")
+                return {
+                    status: "failed",
+                    reason: "authorization_or_package_manager",
+                    packageFailure: install.failure,
+                };
+            const launcherPath = "/opt/hopper/bin/Hopper";
+            const launcherStatus = await host.launcherStatus(launcherPath);
+            if (launcherStatus !== "ready")
+                return {
+                    status: "failed",
+                    reason: launcherStatus === "missing" ? "launcher_missing" : launcherStatus,
+                };
+            return { status: "installed", launcherPath };
+        })();
     }
     catch (cause) {
-        if (isAbortCause(cause))
-            return { status: "failed", reason: "cancelled" };
-        return { status: "failed", reason: "download" };
+        result = {
+            status: "failed",
+            reason: isAbortCause(cause) ? "cancelled" : "download",
+        };
+    }
+    if (temporary === undefined)
+        return result;
+    try {
+        await host.cleanup(temporary);
+        return result;
     }
-    finally {
-        if (temporary !== undefined)
-            await host.cleanup(temporary);
+    catch (cause) {
+        return {
+            ...result,
+            cleanupFailure: {
+                path: temporary,
+                reason: cause instanceof Error ? cause.message : String(cause),
+            },
+        };
     }
 };
 /** Canonical launcher path for a legacy user-local Linux Hopper installation. */
 export const linuxHopperLauncherPath = (home) => join(home, ".local/share/rea/hopper/bin/Hopper");
+/** REA's managed Linux install path, preferred when no explicit launcher is set. */
+export const REA_MANAGED_LINUX_HOPPER_LAUNCHER = "/opt/hopper/bin/Hopper";
+/** Other system-wide Hopper paths used by package installations. */
+export const systemLinuxHopperLauncherCandidates = [
+    "/opt/hopper-v4/bin/hopper",
+    "/usr/bin/hopper",
+];
+/** Probe REA-managed and user-local installs before arbitrary system builds. */
+export const linuxHopperLauncherCandidates = (home) => [
+    REA_MANAGED_LINUX_HOPPER_LAUNCHER,
+    linuxHopperLauncherPath(home),
+    ...systemLinuxHopperLauncherCandidates,
+];
 /** Compose package-manager and linker checks from the selected caller environment. */
 export const systemLinuxHopperInstallHost = (environment) => ({
     distribution: readLinuxDistribution,
@@ -170,19 +235,32 @@ export const linuxHopperLauncherDigestSupported = (digest) => SUPPORTED_HOPPER_S
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
 const installSystemPackage = async (family, archive, environment) => {
-    try {
-        for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0))
-            await execFileAsync(command.executable, command.args, {
-                env: environment,
-            });
-        return true;
-    }
-    catch (cause) {
-        // Package-manager failure is reported by the false return.
-        void cause;
-        return false;
+    for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0)) {
+        const output = await execFileBoundedOutput(command.executable, command.args, {
+            env: environment,
+            limit: PACKAGE_MANAGER_OUTPUT_BYTES,
+        });
+        if (output.exitCode !== 0) {
+            return {
+                status: "failed",
+                failure: {
+                    command: formatCommandForDisplay(command.executable, command.args),
+                    exitCode: output.exitCode,
+                    // The streams stay separate; their original interleaved order
+                    // is not recoverable after capture.
+                    stdout: output.stdout,
+                    stderr: output.stderr,
+                    outputTruncated: output.outputTruncated,
+                },
+            };
+        }
     }
+    return { status: "installed" };
 };
+/** Preserve argument boundaries in a command shown to the user. */
+export const formatCommandForDisplay = (executable, args) => [executable, ...args]
+    .map((part) => /^[A-Za-z0-9_./:@%+=,-]+$/u.test(part) ? part : JSON.stringify(part))
+    .join(" ");
 /** Select the native package manager and authorization boundary without shell evaluation. */
 export const linuxPackageManagerCommands = (family, archive, isRoot) => {
     const runtimeDependencies = family === "deb"