Merge branch 'main' into win-support

Author: satococoa

.gitignore

@@ -36,3 +36,10 @@ Thumbs.db
 # Temporary files
 *.tmp
 *.temp
+
+# Local caches (Codex sandbox / local runs)
+.gocache/
+.gomodcache/
+.gopath/
+.golangci-cache/
+.tmp_repro/

README.md

@@ -58,7 +58,7 @@ requirements.
 path) **wtp solution:** `wtp cd feature/auth` with tab completion
 
 Jump between worktrees instantly. Use `wtp cd @` to return to your main
-worktree. No more terminal tab confusion.
+worktree (or just `wtp cd`). No more terminal tab confusion.
 
 ## Requirements
 
@@ -349,6 +349,9 @@ two ways:
 cd "$(wtp cd feature/auth)"
 
 # Change to the main worktree
+cd "$(wtp cd)"
+
+# Or explicitly:
 cd "$(wtp cd @)"
 ```
 
@@ -365,6 +368,9 @@ Then use the simplified syntax:
 # Change to a worktree by its name
 wtp cd feature/auth
 
+# Go to the main worktree (same as @)
+wtp cd
+
 # Change to the root worktree using the '@' shorthand
 wtp cd @
 

cmd/wtp/cd.go

@@ -28,27 +28,30 @@ func NewCdCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "cd",
 		Usage: "Output absolute path to worktree",
-		Description: "Output the absolute path to the specified worktree.\n\n" +
+		Description: "Output the absolute path to the specified worktree.\n" +
+			"If no worktree is specified, outputs the main worktree path (like cd goes to $HOME).\n\n" +
 			"Usage:\n" +
 			"  Direct:     cd \"$(wtp cd feature)\"\n" +
-			"  With hook:  wtp cd feature\n\n" +
+			"  With hook:  wtp cd feature\n" +
+			"  Go home:    wtp cd\n\n" +
 			"To enable the hook for easier navigation:\n" +
 			"  Bash: eval \"$(wtp hook bash)\"\n" +
 			"  Zsh:  eval \"$(wtp hook zsh)\"\n" +
 			"  Fish: wtp hook fish | source",
-		ArgsUsage:     "<worktree-name>",
+		ArgsUsage:     "[worktree-name]",
 		Action:        cdToWorktree,
 		ShellComplete: completeWorktreesForCd,
 	}
 }
 
 func cdToWorktree(_ context.Context, cmd *cli.Command) error {
 	args := cmd.Args()
-	if args.Len() == 0 {
-		return errors.WorktreeNameRequired()
-	}
 
-	worktreeName := args.Get(0)
+	// Default to main worktree (@) when no argument provided, like cd goes to $HOME
+	worktreeName := "@"
+	if args.Len() > 0 {
+		worktreeName = args.Get(0)
+	}
 
 	// Get current directory
 	cwd, err := os.Getwd()

cmd/wtp/cd_test.go

@@ -1,7 +1,6 @@
 package main
 
 import (
-	"bytes"
 	"context"
 	"os"
 	"path/filepath"
@@ -128,42 +127,6 @@ func TestCdCommand_NoEnvironmentVariableDependency(t *testing.T) {
 	}
 }
 
-// Test critical error scenarios that users will encounter
-func TestCdCommand_UserFacingErrors(t *testing.T) {
-	tests := []struct {
-		name          string
-		args          []string
-		expectedError string
-	}{
-		{
-			name:          "no arguments",
-			args:          []string{},
-			expectedError: "worktree name is required",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			app := &cli.Command{
-				Commands: []*cli.Command{
-					NewCdCommand(),
-				},
-			}
-
-			var buf bytes.Buffer
-			app.Writer = &buf
-
-			ctx := context.Background()
-			cmdArgs := []string{"wtp", "cd"}
-			cmdArgs = append(cmdArgs, tt.args...)
-
-			err := app.Run(ctx, cmdArgs)
-			assert.Error(t, err)
-			assert.Contains(t, err.Error(), tt.expectedError)
-		})
-	}
-}
-
 // Test edge cases that could break in production
 func TestCdCommand_EdgeCases(t *testing.T) {
 	tests := []struct {

cmd/wtp/hook.go

@@ -92,16 +92,20 @@ wtp() {
         fi
     done
     if [[ "$1" == "cd" ]]; then
+        local target_dir
         if [[ -z "$2" ]]; then
-            echo "Usage: wtp cd <worktree>" >&2
-            return 1
+            target_dir=$(command wtp cd 2>/dev/null)
+        else
+            target_dir=$(command wtp cd "$2" 2>/dev/null)
         fi
-        local target_dir
-        target_dir=$(command wtp cd "$2" 2>/dev/null)
         if [[ $? -eq 0 && -n "$target_dir" ]]; then
             cd "$target_dir"
         else
-            command wtp cd "$2"
+            if [[ -z "$2" ]]; then
+                command wtp cd
+            else
+                command wtp cd "$2"
+            fi
         fi
     else
         command wtp "$@"
@@ -121,16 +125,20 @@ wtp() {
         fi
     done
     if [[ "$1" == "cd" ]]; then
+        local target_dir
         if [[ -z "$2" ]]; then
-            echo "Usage: wtp cd <worktree>" >&2
-            return 1
+            target_dir=$(command wtp cd 2>/dev/null)
+        else
+            target_dir=$(command wtp cd "$2" 2>/dev/null)
         fi
-        local target_dir
-        target_dir=$(command wtp cd "$2" 2>/dev/null)
         if [[ $? -eq 0 && -n "$target_dir" ]]; then
             cd "$target_dir"
         else
-            command wtp cd "$2"
+            if [[ -z "$2" ]]; then
+                command wtp cd
+            else
+                command wtp cd "$2"
+            fi
         fi
     else
         command wtp "$@"
@@ -151,14 +159,18 @@ function wtp
     end
     if test "$argv[1]" = "cd"
         if test -z "$argv[2]"
-            echo "Usage: wtp cd <worktree>" >&2
-            return 1
+            set -l target_dir (command wtp cd 2>/dev/null)
+        else
+            set -l target_dir (command wtp cd $argv[2] 2>/dev/null)
         end
-        set -l target_dir (command wtp cd $argv[2] 2>/dev/null)
         if test $status -eq 0 -a -n "$target_dir"
-            cd $target_dir
+            cd "$target_dir"
         else
-            command wtp cd $argv[2]
+            if test -z "$argv[2]"
+                command wtp cd
+            else
+                command wtp cd $argv[2]
+            end
         end
     else
         command wtp $argv

cmd/wtp/hook_test.go

@@ -66,7 +66,7 @@ func TestHookCommand_GeneratesValidShellScripts(t *testing.T) {
 				"function wtp",
 				"if test \"$argv[1]\" = \"cd\"",
 				"command wtp cd",
-				"cd $target_dir",
+				"cd \"$target_dir\"",
 			},
 		},
 	}
@@ -106,23 +106,46 @@ func TestHookScripts_HandleEdgeCases(t *testing.T) {
 		name          string
 		shell         string
 		requiredLogic []string
+		notContains   []string
 	}{
 		{
-			name:  "bash hook handles empty argument",
+			name:  "bash hook supports no-arg cd",
 			shell: "bash",
 			requiredLogic: []string{
-				"if [[ -z \"$2\" ]]", // Empty argument check
-				"echo \"Usage:",      // Error message
-				"return 1",           // Error exit
+				"if [[ -z \"$2\" ]]",               // No-arg branch
+				"target_dir=$(command wtp cd",      // Uses `wtp cd` default behavior
+				"target_dir=$(command wtp cd \"$2", // Uses explicit worktree name when present
+			},
+			notContains: []string{
+				"Usage: wtp cd <worktree>",
+				"echo \"Usage:",
+			},
+		},
+		{
+			name:  "zsh hook supports no-arg cd",
+			shell: "zsh",
+			requiredLogic: []string{
+				"if [[ -z \"$2\" ]]",               // No-arg branch
+				"target_dir=$(command wtp cd",      // Uses `wtp cd` default behavior
+				"target_dir=$(command wtp cd \"$2", // Uses explicit worktree name when present
+			},
+			notContains: []string{
+				"Usage: wtp cd <worktree>",
+				"echo \"Usage:",
 			},
 		},
 		{
-			name:  "fish hook handles empty argument",
+			name:  "fish hook supports no-arg cd",
 			shell: "fish",
 			requiredLogic: []string{
-				"if test -z \"$argv[2]\"", // Empty argument check
-				"echo \"Usage:",           // Error message
-				"return 1",                // Error exit
+				"if test -z \"$argv[2]\"",           // No-arg branch
+				"set -l target_dir (command wtp cd", // Uses `wtp cd` default behavior
+				"command wtp cd $argv[2]",           // Uses explicit worktree name when present
+				"cd \"$target_dir\"",                // Handles spaces safely
+			},
+			notContains: []string{
+				"Usage: wtp cd <worktree>",
+				"echo \"Usage:",
 			},
 		},
 	}
@@ -134,6 +157,8 @@ func TestHookScripts_HandleEdgeCases(t *testing.T) {
 			switch tt.shell {
 			case "bash":
 				require.NoError(t, printBashHook(&buf))
+			case "zsh":
+				require.NoError(t, printZshHook(&buf))
 			case "fish":
 				require.NoError(t, printFishHook(&buf))
 			}
@@ -142,6 +167,9 @@ func TestHookScripts_HandleEdgeCases(t *testing.T) {
 			for _, logic := range tt.requiredLogic {
 				assert.Contains(t, output, logic, "Hook must handle edge cases properly")
 			}
+			for _, unexpected := range tt.notContains {
+				assert.NotContains(t, output, unexpected)
+			}
 		})
 	}
 }

docs/architecture.md

@@ -155,7 +155,7 @@ Following Git's own behavior:
 
 The `wtp cd` command uses a two-part architecture:
 
-1. **Go Command**: `wtp cd <worktree>` finds the worktree path and outputs it
+1. **Go Command**: `wtp cd [worktree]` finds the worktree path and outputs it (defaults to the main worktree when omitted)
 2. **Shell Function**: Wraps the Go command and performs the actual `cd`
 
 ### Shell Integration Flow
@@ -165,7 +165,7 @@ The `wtp cd` command uses a two-part architecture:
 wtp cd feature/auth
 
 # Shell function intercepts, runs:
-WTP_SHELL_INTEGRATION=1 wtp cd feature/auth
+command wtp cd feature/auth
 
 # Go command returns path:
 /path/to/worktrees/feature/auth
@@ -176,8 +176,8 @@ cd /path/to/worktrees/feature/auth
 
 ### Key Design Decisions
 
-- **Environment Variable Check**: `WTP_SHELL_INTEGRATION=1` prevents accidental direct usage
-- **Shell Function Wrapper**: Required because child processes can't change parent's directory
+- **Pure Path Output**: `wtp cd` only prints a path (no side effects), so hooks can safely consume it
+- **Shell Function Wrapper**: Required because child processes can't change the parent shell's directory
 - **Unified Setup Command**: `wtp shell-init <shell>` generates both completion and cd functionality
 - **Cross-Shell Support**: Bash, Zsh, and Fish implementations
 

internal/errors/errors.go

@@ -47,16 +47,6 @@ Examples:
 	return errors.New(msg)
 }
 
-// WorktreeNameRequired reports that a worktree name argument is missing.
-func WorktreeNameRequired() error {
-	msg := `worktree name is required
-
-Usage: wtp cd <worktree-name>
-
-Tip: Run 'wtp list' to see available worktrees`
-	return errors.New(msg)
-}
-
 // WorktreeNameRequiredForRemove reports that a worktree name is required for removal.
 func WorktreeNameRequiredForRemove() error {
 	msg := `worktree name is required

internal/errors/errors_test.go

@@ -79,15 +79,6 @@ func TestBranchNameRequired(t *testing.T) {
 	assert.Contains(t, err.Error(), "Examples:")
 }
 
-func TestWorktreeNameRequired(t *testing.T) {
-	err := WorktreeNameRequired()
-
-	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "worktree name is required")
-	assert.Contains(t, err.Error(), "wtp cd")
-	assert.Contains(t, err.Error(), "wtp list")
-}
-
 func TestWorktreeNameRequiredForRemove(t *testing.T) {
 	err := WorktreeNameRequiredForRemove()
 
@@ -434,9 +425,9 @@ func TestErrorMessages_HelpfulContent(t *testing.T) {
 			keywords: []string{"Solutions:", "git init", "Navigate"},
 		},
 		{
-			name:     "WorktreeNameRequired contains examples",
-			errorFn:  WorktreeNameRequired,
-			keywords: []string{"wtp cd", "wtp list"},
+			name:     "WorktreeNameRequiredForRemove contains examples",
+			errorFn:  WorktreeNameRequiredForRemove,
+			keywords: []string{"wtp remove", "wtp list"},
 		},
 		{
 			name:     "ShellIntegrationRequired contains setup",
@@ -466,7 +457,7 @@ func TestErrorMessages_Format(t *testing.T) {
 	tests := []func() error{
 		NotInGitRepository,
 		func() error { return BranchNameRequired("example") },
-		WorktreeNameRequired,
+		WorktreeNameRequiredForRemove,
 		ShellIntegrationRequired,
 	}