[Feature] Retrieve the actual command in case of failure

[itingliu]

I have several helper functions to call into git through Subprocess like this

    func getCurrentCommitHash(
        at repoPath: FilePath
    ) async throws -> String {
        let gitResult = try await Subprocess.run(
            .at("/usr/local/bin/git"),
            arguments: ["rev-parse", "HEAD"],
            workingDirectory: repoPath
        )
        guard gitResult.terminationStatus.isSuccess else {
            let stderr = String(data: gitResult.standardError, encoding: .utf8)
            throw MyError.commandFailed(
                "git rev-parse HEAD",
                stderr
            )
        }

        return String(decoding: gitResult.standardOutput, as: UTF8.self).trimmingCharacters(in: .whitespacesAndNewlines)
    }

For each of these I am manually constructing an Error to throw when the underlying git command fails. The main body of the error is the actual command that's being run, git rev-parse HEAD in this case.

It would be nice if I can get the underlying command populated up through Subprocess.run. This function already knows the exact command being executed, so it should be possible to also surface this up to the caller.

[iCharlesHu]

Awesome idea!!! I think we can add .executable, and perhaps even .arguments and .environment to SubprocessError to capture this info.

[jakepetroules]

Yes, this would be great, our process abstraction in Swift Build has the same use case. We'd want:

• executable
• arguments
• environment
• working directory
• exit code/signal
• standard input and/or output (if captured).

[broken-circle]

I'd like to take this on. @itingliu @iCharlesHu @jakepetroules, could one of you please assign me?

I'd propose adding a new public type:

public struct ExecutionContext: Sendable, Hashable {
    public let executable: Executable
    public let arguments: Arguments
    public let environment: Environment
    public let workingDirectory: FilePath?
}

Exposed as a new public optional property on SubprocessError. It can be set cleanly by Configuration.run(input:output:error:_:), since every run() overload in API.swift calls into that method.

In the initial PR I'd cover the first four items from the discussion above (executable, arguments, environment, and working directory features). I'd plan to implement the exit code/signal and standard input/output as follow-up PRs, since they involve more design discussion.

Update: Opened #261 as a draft. The implementation involved some design decisions that are easier to evaluate against working code, so I figured a draft PR would be more helpful.