feat: implement deterministic exit codes and structured machine outpu…

CosmosDBShell.Tests/Integration/ShellProcessTests.cs

@@ -6,6 +6,7 @@ namespace CosmosShell.Tests.Integration;
 
 using System.Diagnostics;
 using System.Text;
+using System.Text.Json;
 using System.Text.RegularExpressions;
 using Azure.Data.Cosmos.Shell.Util;
 
@@ -157,7 +158,7 @@ public async Task ConnectOption_WithExecuteAndQuit_RunsCommandAgainstEmulator()
 
         var result = await RunShellAsync(
             stdinScript: null,
-            extraArgs: ["--connect", connectionString, "-c", "connect"],
+            extraArgs: ["--connect", connectionString, "-c", "connect", "--output", "table"],
             cancellationToken: TestContext.Current.CancellationToken);
 
         Assert.Equal(0, result.ExitCode);
@@ -166,6 +167,81 @@ public async Task ConnectOption_WithExecuteAndQuit_RunsCommandAgainstEmulator()
         Assert.Contains("Current Location", result.StdOut, StringComparison.OrdinalIgnoreCase);
     }
 
+    [Fact]
+    public async Task BadArguments_WithOutputJson_ReturnsExitCode2_AndJsonOnStdErr()
+    {
+        var result = await RunShellAsync(
+            stdinScript: null,
+            extraArgs: ["--output", "json", "-c", "not a real command"],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(2, result.ExitCode);
+        Assert.Empty(result.StdOut.Trim());
+        Assert.Contains("\"status\":\"error\"", result.StdErr, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("not recognized as an internal or external command", result.StdErr, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ConnectionFailure_WithOutputJson_ReturnsExitCode3_AndJsonOnStdErr()
+    {
+        var result = await RunShellAsync(
+            stdinScript: null,
+            extraArgs: ["--connect", "https://127.0.0.1:1", "--output", "json", "-c", "version"],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(3, result.ExitCode);
+        Assert.Empty(result.StdOut.Trim());
+        Assert.Contains("\"status\":\"error\"", result.StdErr, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ExecuteAndQuit_WithoutOutput_EmitsParseableNdjsonOnStdOut()
+    {
+        var result = await RunShellAsync(
+            stdinScript: null,
+            extraArgs: ["-c", "version"],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(0, result.ExitCode);
+        Assert.Empty(result.StdErr.Trim());
+
+        var lines = result.StdOut
+            .Split(Environment.NewLine, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        Assert.NotEmpty(lines);
+
+        foreach (var line in lines)
+        {
+            using var doc = JsonDocument.Parse(line);
+            Assert.True(doc.RootElement.ValueKind == JsonValueKind.Object || doc.RootElement.ValueKind == JsonValueKind.Array);
+        }
+    }
+
+    [Fact]
+    public async Task InvalidMcpPort_WithOutputJson_ReturnsExitCode2_AndJsonOnStdErr()
+    {
+        var result = await RunShellAsync(
+            stdinScript: null,
+            extraArgs: ["--output", "json", "--mcp", "0"],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(2, result.ExitCode);
+        Assert.Empty(result.StdOut.Trim());
+        Assert.Contains("\"status\":\"error\"", result.StdErr, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("port", result.StdErr, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public async Task ClearHistory_WithOutputJson_DoesNotWriteInformationalStdOut()
+    {
+        var result = await RunShellAsync(
+            stdinScript: null,
+            extraArgs: ["--output", "json", "--clear-history"],
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(0, result.ExitCode);
+        Assert.Empty(result.StdOut.Trim());
+    }
+
     private static async Task<ShellProcessResult> RunShellAsync(
         string stdinScript,
         CancellationToken cancellationToken)
@@ -178,6 +254,11 @@ private static async Task<ShellProcessResult> RunShellAsync(
         IEnumerable<string>? extraArgs,
         CancellationToken cancellationToken)
     {
+        var argsList = extraArgs?.ToList();
+        var requiresOwnedStdin = stdinScript != null
+            || (argsList?.Contains("-c") == true)
+            || (argsList?.Contains("-k") == true);
+
         var shellDll = Path.Combine(AppContext.BaseDirectory, "CosmosDBShell.dll");
         if (!File.Exists(shellDll))
         {
@@ -191,7 +272,7 @@ private static async Task<ShellProcessResult> RunShellAsync(
             FileName = dotnet,
             WorkingDirectory = AppContext.BaseDirectory,
             UseShellExecute = false,
-            RedirectStandardInput = true,
+            RedirectStandardInput = requiresOwnedStdin,
             RedirectStandardOutput = true,
             RedirectStandardError = true,
             StandardOutputEncoding = Encoding.UTF8,
@@ -200,9 +281,9 @@ private static async Task<ShellProcessResult> RunShellAsync(
         };
 
         startInfo.ArgumentList.Add(shellDll);
-        if (extraArgs != null)
+        if (argsList != null)
         {
-            foreach (var a in extraArgs)
+            foreach (var a in argsList)
             {
                 startInfo.ArgumentList.Add(a);
             }
@@ -239,14 +320,14 @@ private static async Task<ShellProcessResult> RunShellAsync(
         process.BeginOutputReadLine();
         process.BeginErrorReadLine();
 
-        if (stdinScript != null)
-        {
-            await process.StandardInput.WriteAsync(stdinScript);
-            await process.StandardInput.WriteLineAsync();
-            process.StandardInput.Close();
-        }
-        else
+        if (requiresOwnedStdin)
         {
+            if (stdinScript != null)
+            {
+                await process.StandardInput.WriteAsync(stdinScript);
+                await process.StandardInput.WriteLineAsync();
+            }
+
             process.StandardInput.Close();
         }
 

CosmosDBShell.Tests/UtilTest/OutputFormatTests.cs

@@ -31,6 +31,22 @@ void TestJSon()
         Assert.Equal(StripWS(input), StripWS(output));
     }
 
+    [Fact]
+    void TestNdjson()
+    {
+        var input = "[{ \"id\": 12 }, { \"id\": 13 }]";
+        var element = JsonSerializer.Deserialize<JsonElement>(input);
+
+        var commandState = new CommandState();
+        commandState.Result = new ShellJson(element);
+        commandState.OutputFormat = OutputFormat.Ndjson;
+
+        var output = commandState.GenerateOutputText();
+        var expected = "{\"id\":12}" + Environment.NewLine + "{\"id\":13}" + Environment.NewLine;
+
+        Assert.Equal(expected, output);
+    }
+
     [Fact]
     void TestCSV()
     {

CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/ConnectCommand.cs

@@ -55,10 +55,12 @@ internal partial class ConnectCommand : CosmosCommand
 
     public async override Task<CommandState> ExecuteAsync(ShellInterpreter shell, CommandState commandState, string commandText, CancellationToken token)
     {
+        var isQuiet = shell.Options?.Quiet == true;
+
         // If no connection string provided, show current connection info
         if (this.ConnectionString is null)
         {
-            return await PrintConnectionInfoAsync(shell, commandState, token);
+            return await PrintConnectionInfoAsync(shell, commandState, token, isQuiet);
         }
 
         // If already connected, inform user about switching accounts.
@@ -67,7 +69,10 @@ public async override Task<CommandState> ExecuteAsync(ShellInterpreter shell, Co
         if (shell.State is ConnectedState cs)
         {
             var previousEndpoint = cs.Client.Endpoint.Host;
-            AnsiConsole.MarkupLine(MessageService.GetArgsString("command-connect-switching", "endpoint", previousEndpoint));
+            if (!isQuiet)
+            {
+                AnsiConsole.MarkupLine(MessageService.GetArgsString("command-connect-switching", "endpoint", previousEndpoint));
+            }
         }
 
         ConnectionMode? connectionMode = null;
@@ -95,7 +100,7 @@ public async override Task<CommandState> ExecuteAsync(ShellInterpreter shell, Co
             await shell.ConnectAsync(this.ConnectionString, this.LoginHint, connectionMode, tenantId: this.TenantId, authorityHost: this.AuthorityHost, managedIdentityClientId: this.ManagedIdentityClientId, useVSCodeCredential: this.UseVSCodeCredential, subscriptionId: this.SubscriptionId, resourceGroupName: this.ResourceGroupName, token: token);
             var returnState = new CommandState
             {
-                IsPrinted = true,
+                IsPrinted = !isQuiet,
             };
             var endpoint = ParsedDocDBConnectionString.ExtractEndpoint(this.ConnectionString);
             var resultElement = JsonSerializer.SerializeToElement(new Dictionary<string, string?>
@@ -111,7 +116,7 @@ public async override Task<CommandState> ExecuteAsync(ShellInterpreter shell, Co
         }
         catch (Exception e)
         {
-            if (TryGetPrincipalIdFromRbacException(e, out var id, out var permission))
+            if (!isQuiet && TryGetPrincipalIdFromRbacException(e, out var id, out var permission))
             {
                 AskForRBacPermissions(id ?? string.Empty, permission ?? string.Empty);
                 return commandState;
@@ -183,13 +188,16 @@ internal static void PrintConnectUsageHint(ShellInterpreter shell)
         AnsiConsole.MarkupLine(Markup.Escape(MessageService.GetString("command-connect-not_connected-usage-footer")));
     }
 
-    private static async Task<CommandState> PrintConnectionInfoAsync(ShellInterpreter shell, CommandState commandState, CancellationToken token)
+    private static async Task<CommandState> PrintConnectionInfoAsync(ShellInterpreter shell, CommandState commandState, CancellationToken token, bool isQuiet)
     {
         if (shell.State is not ConnectedState connectedState)
         {
-            AnsiConsole.MarkupLine(MessageService.GetString("command-connect-not_connected"));
-            PrintConnectUsageHint(shell);
-            commandState.IsPrinted = true;
+            if (!isQuiet)
+            {
+                AnsiConsole.MarkupLine(MessageService.GetString("command-connect-not_connected"));
+                PrintConnectUsageHint(shell);
+            }
+            commandState.IsPrinted = !isQuiet;
             var notConnectedJson = new Dictionary<string, object?>
             {
                 ["connected"] = false,
@@ -202,36 +210,39 @@ private static async Task<CommandState> PrintConnectionInfoAsync(ShellInterprete
 
         token.ThrowIfCancellationRequested();
         var acc = await client.ReadAccountAsync().WaitAsync(token);
-        AnsiConsole.MarkupLine(Theme.FormatSectionHeader(MessageService.GetString("command-connect-info-title")));
+        var connectionMode = client.ClientOptions.ConnectionMode;
+        string currentLocation = ShellLocation.GetCurrentLocation(shell.State) ?? ShellLocation.NotConnectedText;
 
-        var table = new Table();
-        table.AddColumns(string.Empty, string.Empty);
-        table.HideHeaders();
+        if (!isQuiet)
+        {
+            AnsiConsole.MarkupLine(Theme.FormatSectionHeader(MessageService.GetString("command-connect-info-title")));
 
-        table.AddRow(MessageService.GetString("command-connect-info-account"), Theme.FormatTableValue(acc.Id));
-        table.AddRow(MessageService.GetString("command-connect-info-endpoint"), Theme.FormatTableValue(client.Endpoint.ToString()));
+            var table = new Table();
+            table.AddColumns(string.Empty, string.Empty);
+            table.HideHeaders();
 
-        if (connectedState.ArmContext != null)
-        {
-            table.AddRow(MessageService.GetString("command-connect-info-arm-account"), Theme.FormatTableValue(connectedState.ArmContext.AccountResourceId.ToString()));
-        }
+            table.AddRow(MessageService.GetString("command-connect-info-account"), Theme.FormatTableValue(acc.Id));
+            table.AddRow(MessageService.GetString("command-connect-info-endpoint"), Theme.FormatTableValue(client.Endpoint.ToString()));
 
-        // Display the connection mode
-        var connectionMode = client.ClientOptions.ConnectionMode;
-        table.AddRow(MessageService.GetString("command-connect-info-mode"), Theme.FormatTableValue(connectionMode.ToString()));
+            if (connectedState.ArmContext != null)
+            {
+                table.AddRow(MessageService.GetString("command-connect-info-arm-account"), Theme.FormatTableValue(connectedState.ArmContext.AccountResourceId.ToString()));
+            }
 
-        // Display the readable/writable regions
-        table.AddRow(MessageService.GetString("command-connect-info-read-regions"), Theme.FormatTableValue(string.Join(", ", acc.ReadableRegions.Select(r => r.Name))));
-        table.AddRow(MessageService.GetString("command-connect-info-write-regions"), Theme.FormatTableValue(string.Join(", ", acc.WritableRegions.Select(r => r.Name))));
+            // Display the connection mode
+            table.AddRow(MessageService.GetString("command-connect-info-mode"), Theme.FormatTableValue(connectionMode.ToString()));
 
-        // Show current navigation state
-        string currentLocation = ShellLocation.GetCurrentLocation(shell.State) ?? ShellLocation.NotConnectedText;
+            // Display the readable/writable regions
+            table.AddRow(MessageService.GetString("command-connect-info-read-regions"), Theme.FormatTableValue(string.Join(", ", acc.ReadableRegions.Select(r => r.Name))));
+            table.AddRow(MessageService.GetString("command-connect-info-write-regions"), Theme.FormatTableValue(string.Join(", ", acc.WritableRegions.Select(r => r.Name))));
 
-        table.AddRow(MessageService.GetString("command-connect-info-location"), Theme.ConnectedStatePromt(currentLocation));
+            // Show current navigation state
+            table.AddRow(MessageService.GetString("command-connect-info-location"), Theme.ConnectedStatePromt(currentLocation));
 
-        AnsiConsole.Write(table);
+            AnsiConsole.Write(table);
+        }
 
-        commandState.IsPrinted = true;
+        commandState.IsPrinted = !isQuiet;
         var jsonResult = new Dictionary<string, object?>
         {
             ["connected"] = true,

CosmosDBShell/Azure.Data.Cosmos.Shell.Core/CommandState.cs

@@ -19,6 +19,11 @@ public partial class CommandState
     /// </summary>
     public virtual bool IsError => false;
 
+    /// <summary>
+    /// Gets the exit code for the command state. Default is 0.
+    /// </summary>
+    public virtual int ExitCode => 0;
+
     /// <summary>
     /// Gets or sets the output format for the command result.
     /// </summary>
@@ -55,9 +60,13 @@ internal void SetFormat(string? outputFormat)
         {
             this.OutputFormat = OutputFormat.Table;
         }
+        else if (string.Equals(outputFormat, "ndjson", StringComparison.OrdinalIgnoreCase))
+        {
+            this.OutputFormat = OutputFormat.Ndjson;
+        }
         else
         {
-            throw new ShellException(MessageService.GetString("error-invalid_output_format", new Dictionary<string, object> { { "format", outputFormat } }));
+            throw new ArgumentException(MessageService.GetString("error-invalid_output_format", new Dictionary<string, object> { { "format", outputFormat } }));
         }
     }
 
@@ -123,6 +132,39 @@ internal string GenerateOutputText()
                 }
 
                 return ResultToTable(json.EnumerateArray().ToArray()).ToGridString();
+            case OutputFormat.Ndjson:
+                {
+                    var array = json;
+                    if (json.ValueKind == JsonValueKind.Object)
+                    {
+                        if (json.TryGetProperty("documents", out var documents))
+                        {
+                            array = documents;
+                        }
+                        else if (json.TryGetProperty("items", out var items))
+                        {
+                            array = items;
+                        }
+                        else
+                        {
+                            return JsonSerializer.Serialize(json) + Environment.NewLine;
+                        }
+                    }
+
+                    if (array.ValueKind == JsonValueKind.Array)
+                    {
+                        var sb = new StringBuilder();
+                        foreach (var element in array.EnumerateArray())
+                        {
+                            sb.AppendLine(JsonSerializer.Serialize(element));
+                        }
+
+                        return sb.ToString();
+                    }
+
+                    return JsonSerializer.Serialize(array) + Environment.NewLine;
+                }
+
             default:
                 throw new InvalidOperationException("OutputFormat invalid " + this.OutputFormat);
         }