feat: add machine-readable doctor --json output (#206)

Add a --json flag to the doctor command that emits diagnostics as a
single JSON object. Diagnostics are collected once into a doctorReport
struct that both the text and JSON renderers consume, so the two outputs
cannot drift apart. The default text output is unchanged.

Closes #199

Co-authored-by: Copilot App <[email protected]>

Author: jongio

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### Added
 - **Configurable auto-refresh** — set `auto_refresh_seconds` (also in the settings panel) to tune the session-list poll interval, or set it to `0` to turn polling off and refresh only with `r` or reindex
+- **Machine-readable doctor output** — `dispatch doctor --json` prints diagnostics as a single JSON object so scripts and CI can parse them instead of scraping text
 
 ## [v0.13.0] — 2026-06-30
 

README.md

@@ -143,6 +143,8 @@ dispatch completion powershell
 
 Run `dispatch doctor` to print setup checks for the config file, session store, session-state directory, and Copilot CLI binary.
 
+Add `--json` (`dispatch doctor --json`) to print the same checks as a single JSON object for scripts and CI.
+
 ### Key Bindings
 
 #### Navigation

cmd/dispatch/cli.go

@@ -2,12 +2,14 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"os"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strings"
 
 	"github.com/jongio/dispatch/internal/config"
@@ -65,7 +67,14 @@ func handleArgs(args []string, origStderr io.Writer, updateCh <-chan *update.Upd
 			return true, cleanup, nil
 
 		case "doctor":
-			runDoctor(os.Stdout)
+			if slices.Contains(args, "--json") {
+				if jErr := runDoctorJSON(os.Stdout); jErr != nil {
+					fmt.Fprintf(os.Stderr, "doctor: %v\n", jErr)
+					return true, cleanup, jErr
+				}
+			} else {
+				runDoctor(os.Stdout)
+			}
 			showUpdateNotification(origStderr, updateCh)
 			return true, cleanup, nil
 
@@ -207,56 +216,136 @@ Register-ArgumentCompleter -Native -CommandName dispatch, disp -ScriptBlock {
 }
 `
 
-func runDoctor(w io.Writer) {
-	if w == nil {
-		w = io.Discard
-	}
+// doctorStatus values describe the result of a single diagnostic path check.
+const (
+	statusFound     = "found"
+	statusMissing   = "missing"
+	statusWrongType = "wrong_type"
+	statusError     = "error"
+)
 
-	fmt.Fprintf(w, "Dispatch doctor\n")
-	fmt.Fprintf(w, "Version: %s\n", version.Version)
-	fmt.Fprintf(w, "OS: %s/%s\n", runtime.GOOS, runtime.GOARCH)
-	fmt.Fprintf(w, "\n")
+// doctorEntry is the diagnostic result for one path. The err field is used
+// only by the text renderer and is not serialized to JSON.
+type doctorEntry struct {
+	Path   string `json:"path"`
+	Status string `json:"status"`
+	err    error
+}
+
+// doctorReport is the full set of diagnostics gathered by the doctor command.
+// Both the text and JSON renderers consume this struct so their outputs stay
+// in sync.
+type doctorReport struct {
+	Version      string      `json:"version"`
+	OS           string      `json:"os"`
+	Config       doctorEntry `json:"config"`
+	SessionStore doctorEntry `json:"session_store"`
+	SessionState doctorEntry `json:"session_state"`
+	CopilotCLI   doctorEntry `json:"copilot_cli"`
+}
+
+// collectDoctorReport gathers the environment diagnostics once so they can be
+// rendered as text or JSON without drifting apart.
+func collectDoctorReport() doctorReport {
+	r := doctorReport{
+		Version: version.Version,
+		OS:      runtime.GOOS + "/" + runtime.GOARCH,
+	}
 
 	if p, err := config.ConfigPath(); err != nil {
-		fmt.Fprintf(w, "Config: error: %v\n", err)
+		r.Config = doctorEntry{Status: statusError, err: err}
 	} else {
-		printPathStatus(w, "Config", p, false)
+		r.Config = doctorEntry{Path: p, Status: pathStatus(p, false)}
 	}
 
 	if p, err := platform.SessionStorePath(); err != nil {
-		fmt.Fprintf(w, "Session store: error: %v\n", err)
+		r.SessionStore = doctorEntry{Status: statusError, err: err}
 	} else {
-		printPathStatus(w, "Session store", p, false)
+		r.SessionStore = doctorEntry{Path: p, Status: pathStatus(p, false)}
 	}
 
 	if p := data.SessionStatePath(); p == "" {
-		fmt.Fprintf(w, "Session state: missing\n")
+		r.SessionState = doctorEntry{Status: statusMissing}
 	} else {
-		printPathStatus(w, "Session state", p, true)
+		r.SessionState = doctorEntry{Path: p, Status: pathStatus(p, true)}
 	}
 
 	if p := platform.FindCLIBinary(); p == "" {
-		fmt.Fprintf(w, "Copilot CLI: missing\n")
+		r.CopilotCLI = doctorEntry{Status: statusMissing}
 	} else {
-		fmt.Fprintf(w, "Copilot CLI: found (%s)\n", p)
+		r.CopilotCLI = doctorEntry{Path: p, Status: statusFound}
 	}
+
+	return r
 }
 
-func printPathStatus(w io.Writer, label, path string, wantDir bool) {
+// pathStatus stats a path and reports whether it is found, missing, or the
+// wrong type (a file where a directory is expected, or vice versa).
+func pathStatus(path string, wantDir bool) string {
 	info, err := os.Stat(path)
 	if err != nil {
-		fmt.Fprintf(w, "%s: missing (%s)\n", label, path)
-		return
+		return statusMissing
 	}
-	if wantDir && !info.IsDir() {
-		fmt.Fprintf(w, "%s: wrong type, expected directory (%s)\n", label, path)
-		return
+	if wantDir != info.IsDir() {
+		return statusWrongType
+	}
+	return statusFound
+}
+
+func runDoctor(w io.Writer) {
+	if w == nil {
+		w = io.Discard
 	}
-	if !wantDir && info.IsDir() {
-		fmt.Fprintf(w, "%s: wrong type, expected file (%s)\n", label, path)
+
+	r := collectDoctorReport()
+
+	fmt.Fprintf(w, "Dispatch doctor\n")
+	fmt.Fprintf(w, "Version: %s\n", r.Version)
+	fmt.Fprintf(w, "OS: %s\n", r.OS)
+	fmt.Fprintf(w, "\n")
+
+	writeDoctorLine(w, "Config", r.Config, false)
+	writeDoctorLine(w, "Session store", r.SessionStore, false)
+	writeDoctorLine(w, "Session state", r.SessionState, true)
+	writeDoctorLine(w, "Copilot CLI", r.CopilotCLI, false)
+}
+
+// runDoctorJSON writes the diagnostics as a single JSON object followed by a
+// newline.
+func runDoctorJSON(w io.Writer) error {
+	if w == nil {
+		w = io.Discard
+	}
+	b, err := json.MarshalIndent(collectDoctorReport(), "", "  ")
+	if err != nil {
+		return err
+	}
+	fmt.Fprintf(w, "%s\n", b)
+	return nil
+}
+
+// writeDoctorLine renders one diagnostic entry as human-readable text.
+func writeDoctorLine(w io.Writer, label string, e doctorEntry, wantDir bool) {
+	if e.err != nil {
+		fmt.Fprintf(w, "%s: error: %v\n", label, e.err)
 		return
 	}
-	fmt.Fprintf(w, "%s: found (%s)\n", label, path)
+	switch e.Status {
+	case statusMissing:
+		if e.Path == "" {
+			fmt.Fprintf(w, "%s: missing\n", label)
+		} else {
+			fmt.Fprintf(w, "%s: missing (%s)\n", label, e.Path)
+		}
+	case statusWrongType:
+		if wantDir {
+			fmt.Fprintf(w, "%s: wrong type, expected directory (%s)\n", label, e.Path)
+		} else {
+			fmt.Fprintf(w, "%s: wrong type, expected file (%s)\n", label, e.Path)
+		}
+	default:
+		fmt.Fprintf(w, "%s: found (%s)\n", label, e.Path)
+	}
 }
 
 // setupLogRedirect opens the log file (if configured via DISPATCH_LOG) and

cmd/dispatch/cli_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"os"
@@ -171,6 +172,74 @@ func TestRunDoctor_PrintsDiagnostics(t *testing.T) {
 	}
 }
 
+func TestRunDoctorJSON_Shape(t *testing.T) {
+	db := filepath.Join(t.TempDir(), "session-store.db")
+	if err := os.WriteFile(db, []byte("sqlite"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	stateDir := t.TempDir()
+	t.Setenv("DISPATCH_DB", db)
+	t.Setenv("DISPATCH_SESSION_STATE", stateDir)
+
+	var buf bytes.Buffer
+	if err := runDoctorJSON(&buf); err != nil {
+		t.Fatalf("runDoctorJSON: %v", err)
+	}
+
+	var r doctorReport
+	if err := json.Unmarshal(buf.Bytes(), &r); err != nil {
+		t.Fatalf("output is not valid JSON: %v\n%s", err, buf.String())
+	}
+	if r.Version == "" {
+		t.Error("version should be set")
+	}
+	if r.OS == "" {
+		t.Error("os should be set")
+	}
+	if r.SessionStore.Status != statusFound {
+		t.Errorf("session_store status = %q, want %q", r.SessionStore.Status, statusFound)
+	}
+	if r.SessionState.Status != statusFound {
+		t.Errorf("session_state status = %q, want %q", r.SessionState.Status, statusFound)
+	}
+	if !strings.HasSuffix(buf.String(), "}\n") {
+		t.Errorf("JSON output should end with a single newline, got:\n%q", buf.String())
+	}
+}
+
+func TestPathStatus_Cases(t *testing.T) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "f.txt")
+	if err := os.WriteFile(file, []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if got := pathStatus(file, false); got != statusFound {
+		t.Errorf("file wantDir=false: got %q, want %q", got, statusFound)
+	}
+	if got := pathStatus(dir, true); got != statusFound {
+		t.Errorf("dir wantDir=true: got %q, want %q", got, statusFound)
+	}
+	if got := pathStatus(filepath.Join(dir, "nope"), false); got != statusMissing {
+		t.Errorf("missing: got %q, want %q", got, statusMissing)
+	}
+	if got := pathStatus(file, true); got != statusWrongType {
+		t.Errorf("file wantDir=true: got %q, want %q", got, statusWrongType)
+	}
+	if got := pathStatus(dir, false); got != statusWrongType {
+		t.Errorf("dir wantDir=false: got %q, want %q", got, statusWrongType)
+	}
+}
+
+func TestHandleArgs_DoctorJSON(t *testing.T) {
+	ch := make(chan *update.UpdateInfo, 1)
+	ch <- nil
+
+	done, _, err := handleArgs([]string{"doctor", "--json"}, io.Discard, ch)
+	if err != nil || !done {
+		t.Errorf("expected done=true, no error for doctor --json; got done=%v, err=%v", done, err)
+	}
+}
+
 func TestHandleArgs_Doctor(t *testing.T) {
 	ch := make(chan *update.UpdateInfo, 1)
 	ch <- nil

cmd/dispatch/main.go

@@ -92,7 +92,7 @@ Commands:
   version                 Print the version
   open <id> [--mode M]    Resume a session by ID (M: inplace, tab, window, pane)
   completion <shell>      Print shell completion (bash, zsh, powershell)
-  doctor                  Print environment diagnostics
+  doctor [--json]         Print environment diagnostics (--json for machine-readable output)
   stats [flags]           Print session totals and breakdowns
   update                  Update dispatch to the latest release