response: add Yield() for helpers that have nothing to offer

GitResponse already distinguishes "I produced a credential" (Ok)
from "stop the whole acquisition pipeline" (Cancel, wired as
quit=1). There is a third shape the credential helper protocol
expects: "I have nothing to contribute for this request, but I'm
not stopping you -- please try other helpers or fall back to your
interactive prompt." Today providers have no clean way to say
this; they either throw (wrong: a no-op is not an error) or
construct a response with empty credentials (wrong: that's the
WIA signal and gets stored).

Add a Yield() factory that returns a response whose IsYielded
flag is set. The command layer translates it into an empty
response on standard output: just the terminating blank line, no
credential fields, no quit signal. Git then proceeds to the next
helper in the chain or to its built-in interactive prompt --
which is the exact behaviour Git defaults to when a helper
returns nothing, so this is the most polite "I'm out" a helper
can send.

Keep the response shape constructor enforcing that Ok / Cancel /
Yield are mutually exclusive: a response carrying a credential
cannot be cancelled or yielded, and a response cannot be both
cancelled and yielded at once. AdditionalProperties continue to
be ignored on the non-Ok shapes.

Signed-off-by: Matthew John Cheetham <mjcheetham@outlook.com>
Assisted-by: Claude Opus 4.7

Author: mjcheetham

src/Core.Tests/Commands/GetCommandTests.cs

@@ -146,6 +146,30 @@ public async Task GetCommand_ExecuteAsync_CancelledResponse_EmitsQuitAndNoCreden
             Assert.Equal("quit=1\n\n", actualOutput);
         }
 
+        [Fact]
+        public async Task GetCommand_ExecuteAsync_YieldedResponse_EmitsEmptyResponse()
+        {
+            // A provider that has nothing to contribute but does not want to stop
+            // the pipeline returns GitResponse.Yield(); the command MUST emit just
+            // the terminating blank line (no credential fields, no quit signal) so
+            // Git proceeds to the next helper or its interactive prompt.
+            var stdin = "protocol=https\nhost=example.com\n\n";
+
+            var providerMock = new Mock<IHostProvider>();
+            providerMock.Setup(x => x.GetCredentialAsync(It.IsAny<GitRequest>()))
+                        .ReturnsAsync(GitResponse.Yield());
+            var providerRegistry = new TestHostProviderRegistry { Provider = providerMock.Object };
+            var context = new TestCommandContext { Streams = { In = stdin } };
+
+            var command = new GetCommand(context, providerRegistry);
+
+            await command.ExecuteAsync();
+
+            string actualOutput = context.Streams.Out.ToString().Replace("\r\n", "\n");
+
+            Assert.Equal("\n", actualOutput);
+        }
+
         #region Helpers
 
         private static IDictionary<string, string> ParseDictionary(StringBuilder sb) => ParseDictionary(sb.ToString());

src/Core.Tests/GitResponseTests.cs

@@ -83,6 +83,26 @@ public void GitResponse_Cancel_ReturnsCancellationResponseWithNoCredential()
         var response = GitResponse.Cancel();
 
         Assert.True(response.IsCancelled);
+        Assert.False(response.IsYielded);
         Assert.Null(response.Credential);
     }
+
+    [Fact]
+    public void GitResponse_Yield_ReturnsYieldedResponseWithNoCredential()
+    {
+        var response = GitResponse.Yield();
+
+        Assert.True(response.IsYielded);
+        Assert.False(response.IsCancelled);
+        Assert.Null(response.Credential);
+    }
+
+    [Fact]
+    public void GitResponse_Ok_IsNeitherCancelledNorYielded()
+    {
+        var response = GitResponse.Ok(new GitCredential("alice", "hunter2"));
+
+        Assert.False(response.IsCancelled);
+        Assert.False(response.IsYielded);
+    }
 }

src/Core/Commands/GetCommand.cs

@@ -33,6 +33,16 @@ protected override async Task ExecuteInternalAsync(GitRequest request, IHostProv
                 return;
             }
 
+            if (response.IsYielded)
+            {
+                // Provider has nothing to contribute but does not want to stop the
+                // pipeline. Emit an empty response (just the terminating blank line)
+                // so Git proceeds to the next helper or its interactive prompt.
+                Context.Trace.WriteLine("Provider yielded; emitting empty response.");
+                Context.Streams.Out.WriteLine();
+                return;
+            }
+
             ICredential credential = response.Credential;
 
             // Negotiate capabilities by intersecting what Git advertised with what GCM supports.

src/Core/GitResponse.cs

@@ -9,22 +9,20 @@ namespace GitCredentialManager;
 /// </summary>
 /// <remarks>
 /// <para>
-/// A successful response holds the resolved <see cref="ICredential"/> together
-/// with any non-credential output the provider wants to emit back to Git
-/// (see <see cref="AdditionalProperties"/>).
+/// A response is exactly one of three shapes:
 /// </para>
+/// <list type="bullet">
+///   <item><see cref="Ok(ICredential)"/> -- the provider produced a credential.</item>
+///   <item><see cref="Cancel"/> -- the provider declined and wants the whole
+///     credential acquisition pipeline to stop (emits <c>quit=1</c>; Git aborts
+///     the operation without a fallback interactive prompt).</item>
+///   <item><see cref="Yield"/> -- the provider has nothing to contribute but
+///     wants Git to continue trying other helpers or fall back to its built-in
+///     interactive prompt (emits an empty response).</item>
+/// </list>
 /// <para>
-/// A response can also be a <em>cancellation</em>: the provider was asked for a
-/// credential but deliberately declined to produce one (the user closed an
-/// auth prompt, no eligible account was found, and so on). A cancelled
-/// response has no <see cref="Credential"/> and causes the command layer to
-/// emit <c>quit=1</c> to Git, which terminates the credential acquisition
-/// pipeline without falling back to an interactive prompt.
-/// </para>
-/// <para>
-/// Use the <see cref="Ok(ICredential)"/> and <see cref="Cancel"/> factory
-/// methods rather than the constructor where possible; they make the intent
-/// of each call site obvious.
+/// Use the factory methods rather than the constructor where possible; they
+/// make the intent of each call site obvious.
 /// </para>
 /// <para>
 /// Strongly-typed properties for newer Git credential protocol fields
@@ -38,44 +36,52 @@ namespace GitCredentialManager;
 /// </remarks>
 public class GitResponse
 {
-    private GitResponse(ICredential credential, bool isCancelled)
+    private GitResponse(ICredential credential, bool isCancelled, bool isYielded)
     {
-        if (isCancelled && credential is not null)
+        if (isCancelled && isYielded)
         {
             throw new ArgumentException(
-                "A cancelled response cannot carry a credential.",
+                "A response cannot be both cancelled and yielded.");
+        }
+
+        if ((isCancelled || isYielded) && credential is not null)
+        {
+            throw new ArgumentException(
+                "A cancelled or yielded response cannot carry a credential.",
                 nameof(credential));
         }
 
-        if (!isCancelled && credential is null)
+        if (!isCancelled && !isYielded && credential is null)
         {
             throw new ArgumentNullException(
                 nameof(credential),
-                "A non-cancelled response must carry a credential. Use Cancel() instead.");
+                "A successful response must carry a credential. Use Cancel() or Yield() instead.");
         }
 
         Credential = credential;
         IsCancelled = isCancelled;
+        IsYielded = isYielded;
     }
 
     /// <summary>
     /// Construct a successful response carrying the given credential.
     /// </summary>
     /// <remarks>Equivalent to <see cref="Ok(ICredential)"/>.</remarks>
     public GitResponse(ICredential credential)
-        : this(credential, isCancelled: false)
+        : this(credential, isCancelled: false, isYielded: false)
     {
     }
 
     /// <summary>
     /// Construct a successful response carrying the given credential.
     /// </summary>
     public static GitResponse Ok(ICredential credential) =>
-        new GitResponse(credential, isCancelled: false);
+        new GitResponse(credential, isCancelled: false, isYielded: false);
 
     /// <summary>
     /// Construct a cancellation response: the provider declined to produce a
-    /// credential for this request.
+    /// credential for this request, and the whole credential acquisition
+    /// pipeline should stop.
     /// </summary>
     /// <remarks>
     /// The command layer translates a cancelled response into a <c>quit=1</c>
@@ -85,28 +91,52 @@ public static GitResponse Ok(ICredential credential) =>
     /// response are ignored.
     /// </remarks>
     public static GitResponse Cancel() =>
-        new GitResponse(credential: null, isCancelled: true);
+        new GitResponse(credential: null, isCancelled: true, isYielded: false);
+
+    /// <summary>
+    /// Construct a yielded response: the provider has nothing to contribute
+    /// for this request but does not want to stop other helpers from being
+    /// tried (or Git's interactive prompt from being shown).
+    /// </summary>
+    /// <remarks>
+    /// The command layer translates a yielded response into an empty response
+    /// on standard output (no credential fields, no <c>quit</c> signal). Git
+    /// then proceeds to the next helper in the chain or to its built-in
+    /// interactive prompt. Any <see cref="AdditionalProperties"/> set on a
+    /// yielded response are ignored.
+    /// </remarks>
+    public static GitResponse Yield() =>
+        new GitResponse(credential: null, isCancelled: false, isYielded: true);
 
     /// <summary>
     /// The credential resolved or generated for the request, or <see langword="null"/>
-    /// when <see cref="IsCancelled"/> is <see langword="true"/>.
+    /// when <see cref="IsCancelled"/> or <see cref="IsYielded"/> is <see langword="true"/>.
     /// </summary>
     public ICredential Credential { get; }
 
     /// <summary>
     /// <see langword="true"/> when the provider declined to produce a credential
-    /// for this request. The command layer translates this into a <c>quit=1</c>
-    /// signal to Git rather than any specific exit code.
+    /// for this request and wants the whole credential acquisition pipeline to
+    /// stop. The command layer translates this into a <c>quit=1</c> signal to
+    /// Git.
     /// </summary>
     public bool IsCancelled { get; }
 
+    /// <summary>
+    /// <see langword="true"/> when the provider has nothing to contribute but
+    /// does not want to stop the credential acquisition pipeline. The command
+    /// layer translates this into an empty response on standard output so Git
+    /// proceeds to the next helper or its interactive prompt.
+    /// </summary>
+    public bool IsYielded { get; }
+
     /// <summary>
     /// Additional, untyped output to be emitted alongside the credential.
     /// </summary>
     /// <remarks>
     /// This is the legacy escape hatch for non-credential output. New code
     /// should prefer typed properties on <see cref="GitResponse"/> as they
-    /// are added. Ignored on cancelled responses.
+    /// are added. Ignored on cancelled and yielded responses.
     /// </remarks>
     public IDictionary<string, string> AdditionalProperties { get; set; }
         = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);