feat: add examples command and machine-readable json output (#60)

* feat: add examples command and machine-readable json output

* docs: add migrate examples topic

* docs: make examples full-catalog and outcome-focused

* feat: improve examples UX and add json help envelopes

* docs: add config-aware path examples to examples output

* docs: add concrete text and json output samples to examples

* docs: include concrete samples for all examples entries

* fix: align config parity and expand strategy examples

* test: harden e2e string matching across shells

* test: relax powershell-variant unknown-command assertion

* test: stabilize powershell e2e output assertions

* feat: enforce examples and json parity across commands

* test: relax shellenv json substring assertion

Author: timvw

README.md

@@ -185,8 +185,36 @@ wt config path          # Print the config file path
 # Show help
 wt --help
 wt <command> --help
+
+# Show practical examples
+wt examples
+
+# Use machine-readable output
+wt --format json version
+wt --format json list
+wt --format json
+```
+
+### JSON Output (`--format json`)
+
+Most commands support machine-readable JSON output:
+
+```bash
+wt --format json version
+wt --format json info
+wt --format json config show
+wt --format json list
+wt --format json examples
+wt --format json          # root help in JSON envelope
 ```
 
+Important behavior for shell integration:
+
+- In `text` mode (default), shell integration may auto-navigate to the target worktree.
+- In `json` mode, output is kept machine-readable and shell integration does **not** auto-navigate.
+
+For commands that normally prompt interactively (`wt co`, `wt rm`, `wt pr`, `wt mr`), pass explicit arguments when using `--format json`.
+
 ### Interactive Selection
 
 When you run `wt co`, `wt rm`, `wt pr`, or `wt mr` without arguments, you'll get an interactive selection menu:
@@ -248,6 +276,16 @@ wt list
 
 # Remove a worktree when done
 wt rm add-auth-feature
+
+# Show full examples catalog (filter with rg/grep if needed)
+wt examples
+
+# Each example includes outcome + path illustration based on config pattern
+# e.g. path example: $WORKTREE_ROOT/<repo>/<branch> -> (removed)
+# and concrete text/json output samples where relevant
+
+# JSON mode does not auto-navigate; use returned navigate_to
+wt --format json create add-auth-feature
 ```
 
 ## Configuration

config_test.go

@@ -1,8 +1,12 @@
 package main
 
 import (
+	"bytes"
+	"encoding/json"
+	"io"
 	"os"
 	"path/filepath"
+	"regexp"
 	"runtime"
 	"strings"
 	"testing"
@@ -403,3 +407,140 @@ strategy = "global"
 		}
 	})
 }
+
+func TestConfigShowPatternParityBetweenTextAndJSON_Config(t *testing.T) {
+	origRoot := worktreeRoot
+	origStrategy := worktreeStrategy
+	origPattern := worktreePattern
+	origSeparator := worktreeSeparator
+	origConfigFilePath := configFilePath
+	origConfigFileFound := configFileFound
+	origConfigSources := configSources
+	origOutputFormat := outputFormat
+
+	t.Cleanup(func() {
+		worktreeRoot = origRoot
+		worktreeStrategy = origStrategy
+		worktreePattern = origPattern
+		worktreeSeparator = origSeparator
+		configFilePath = origConfigFilePath
+		configFileFound = origConfigFileFound
+		configSources = origConfigSources
+		outputFormat = origOutputFormat
+	})
+
+	runConfigShow := func(t *testing.T, format string) string {
+		t.Helper()
+
+		origStdout := os.Stdout
+		r, w, err := os.Pipe()
+		if err != nil {
+			t.Fatalf("failed to create pipe: %v", err)
+		}
+		os.Stdout = w
+		defer func() {
+			os.Stdout = origStdout
+		}()
+
+		outputFormat = format
+		if err := configShowCmd.RunE(configShowCmd, nil); err != nil {
+			t.Fatalf("config show failed for format %s: %v", format, err)
+		}
+
+		if err := w.Close(); err != nil {
+			t.Fatalf("failed to close write pipe: %v", err)
+		}
+
+		var buf bytes.Buffer
+		if _, err := io.Copy(&buf, r); err != nil {
+			t.Fatalf("failed to read command output: %v", err)
+		}
+
+		return buf.String()
+	}
+
+	tests := []struct {
+		name          string
+		strategy      string
+		workPattern   string
+		patternSource string
+		expected      string
+	}{
+		{
+			name:          "strategy default pattern",
+			strategy:      "global",
+			workPattern:   "",
+			patternSource: "strategy default",
+			expected:      "{.worktreeRoot}/{.repo.Name}/{.branch}",
+		},
+		{
+			name:          "explicit configured pattern",
+			strategy:      "global",
+			workPattern:   "{.worktreeRoot}/custom/{.branch}",
+			patternSource: "config file",
+			expected:      "{.worktreeRoot}/custom/{.branch}",
+		},
+		{
+			name:          "custom strategy without explicit pattern",
+			strategy:      "custom",
+			workPattern:   "",
+			patternSource: "default",
+			expected:      "(none)",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			worktreeRoot = "/tmp/worktrees"
+			worktreeStrategy = tt.strategy
+			worktreePattern = tt.workPattern
+			worktreeSeparator = "-"
+			configFilePath = "/tmp/config.toml"
+			configFileFound = true
+			configSources = configSource{
+				Root:      "config file",
+				Strategy:  "config file",
+				Pattern:   tt.patternSource,
+				Separator: "default",
+			}
+
+			textOut := runConfigShow(t, "text")
+			jsonOut := runConfigShow(t, "json")
+
+			textPatternRe := regexp.MustCompile(`(?m)^\s*pattern\s*=\s*(.*?)\s+\(`)
+			textMatch := textPatternRe.FindStringSubmatch(textOut)
+			if len(textMatch) != 2 {
+				t.Fatalf("failed to parse pattern from text output: %q", textOut)
+			}
+			textPattern := textMatch[1]
+
+			var payload struct {
+				Data struct {
+					Effective struct {
+						Pattern struct {
+							Value string `json:"value"`
+						} `json:"pattern"`
+					} `json:"effective"`
+				} `json:"data"`
+			}
+			if err := json.Unmarshal([]byte(jsonOut), &payload); err != nil {
+				t.Fatalf("failed to parse json output: %v\noutput=%q", err, jsonOut)
+			}
+
+			if payload.Data.Effective.Pattern.Value != textPattern {
+				t.Fatalf("pattern mismatch between text and json: text=%q json=%q", textPattern, payload.Data.Effective.Pattern.Value)
+			}
+
+			expectedPattern := configShowPatternValue()
+			if expectedPattern != tt.expected {
+				t.Fatalf("resolved test expectation mismatch: got=%q want=%q", expectedPattern, tt.expected)
+			}
+			if textPattern != expectedPattern {
+				t.Fatalf("text output pattern should use resolved value: got=%q want=%q", textPattern, expectedPattern)
+			}
+			if payload.Data.Effective.Pattern.Value != expectedPattern {
+				t.Fatalf("json output pattern should use resolved value: got=%q want=%q", payload.Data.Effective.Pattern.Value, expectedPattern)
+			}
+		})
+	}
+}

e2e/run.go

@@ -449,12 +449,14 @@ func generatePosixScript(wtBinary, shell string, scenario Scenario, verbose, sho
 						step.Expect.Branch, step.Expect.Branch))
 				}
 				if step.Expect.OutputContains != "" {
-					sb.WriteString(fmt.Sprintf("echo \"$__output\" | grep -q '%s' || { echo \"Output missing '%s'\"; exit 1; }\n",
-						step.Expect.OutputContains, step.Expect.OutputContains))
+					contains := strings.ReplaceAll(step.Expect.OutputContains, "'", "'\\''")
+					sb.WriteString(fmt.Sprintf("echo \"$__output\" | grep -F -q -- '%s' || { echo \"Output missing expected substring\"; exit 1; }\n",
+						contains))
 				}
 				if step.Expect.OutputNotContains != "" {
-					sb.WriteString(fmt.Sprintf("echo \"$__output\" | grep -q '%s' && { echo \"Output should not contain '%s'\"; exit 1; } || true\n",
-						step.Expect.OutputNotContains, step.Expect.OutputNotContains))
+					notContains := strings.ReplaceAll(step.Expect.OutputNotContains, "'", "'\\''")
+					sb.WriteString(fmt.Sprintf("echo \"$__output\" | grep -F -q -- '%s' && { echo \"Output should not contain expected substring\"; exit 1; } || true\n",
+						notContains))
 				}
 			}
 		}
@@ -488,7 +490,11 @@ func generatePowerShellScript(wtBinary string, scenario Scenario, verbose, showO
 	// Header
 	sb.WriteString("$ErrorActionPreference = 'Stop'\n")
 	sb.WriteString(fmt.Sprintf("$env:WT_BIN = '%s'\n", wtBinary))
-	sb.WriteString("$TestDir = Join-Path $env:TEMP \"wt-e2e-$(Get-Random)\"\n")
+	sb.WriteString("$__tmpBase = [System.IO.Path]::GetTempPath()\n")
+	sb.WriteString("if (-not $__tmpBase) { $__tmpBase = $env:TEMP }\n")
+	sb.WriteString("if (-not $__tmpBase) { $__tmpBase = $env:TMP }\n")
+	sb.WriteString("if (-not $__tmpBase) { $__tmpBase = $PWD.Path }\n")
+	sb.WriteString("$TestDir = Join-Path $__tmpBase \"wt-e2e-$(Get-Random)\"\n")
 	sb.WriteString("$RepoDir = Join-Path $TestDir 'test-repo'\n")
 	sb.WriteString("$env:WORKTREE_ROOT = Join-Path $TestDir 'worktrees'\n")
 	sb.WriteString("New-Item -ItemType Directory -Path $RepoDir -Force | Out-Null\n")
@@ -563,6 +569,10 @@ func generatePowerShellScript(wtBinary string, scenario Scenario, verbose, showO
 			needsOutput := step.Expect != nil && (step.Expect.OutputContains != "" || step.Expect.OutputNotContains != "")
 			expectsNonZero := step.Expect != nil && step.Expect.ExitCode != nil && *step.Expect.ExitCode != 0
 
+			if needsOutput {
+				sb.WriteString("$__output = ''\n")
+			}
+
 			if expectsNonZero {
 				// Handle expected non-zero exit codes
 				sb.WriteString("$__exit_code = 0\n")
@@ -574,6 +584,9 @@ func generatePowerShellScript(wtBinary string, scenario Scenario, verbose, showO
 				}
 				sb.WriteString("  $__exit_code = $LASTEXITCODE\n")
 				sb.WriteString("} catch {\n")
+				if needsOutput {
+					sb.WriteString("  $__output = ($_ | Out-String)\n")
+				}
 				sb.WriteString("  $__exit_code = 1\n")
 				sb.WriteString("}\n")
 			} else if needsOutput {
@@ -604,12 +617,16 @@ func generatePowerShellScript(wtBinary string, scenario Scenario, verbose, showO
 						step.Expect.Branch, step.Expect.Branch))
 				}
 				if step.Expect.OutputContains != "" {
-					sb.WriteString(fmt.Sprintf("if (-not $__output.Contains('%s')) { throw \"Output missing '%s'\" }\n",
-						step.Expect.OutputContains, step.Expect.OutputContains))
+					contains := strings.ReplaceAll(step.Expect.OutputContains, "'", "''")
+					sb.WriteString("if ($null -eq $__output) { $__output = '' }\n")
+					sb.WriteString(fmt.Sprintf("if (-not $__output.Contains('%s')) { throw \"Output missing expected substring\" }\n",
+						contains))
 				}
 				if step.Expect.OutputNotContains != "" {
-					sb.WriteString(fmt.Sprintf("if ($__output.Contains('%s')) { throw \"Output should not contain '%s'\" }\n",
-						step.Expect.OutputNotContains, step.Expect.OutputNotContains))
+					notContains := strings.ReplaceAll(step.Expect.OutputNotContains, "'", "''")
+					sb.WriteString("if ($null -eq $__output) { $__output = '' }\n")
+					sb.WriteString(fmt.Sprintf("if ($__output.Contains('%s')) { throw \"Output should not contain expected substring\" }\n",
+						notContains))
 				}
 			}
 		}