refactor: harden default command routing and help tests

Author: firede

cmd/agent-fetch/main.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"net/http"
 	"os"
 	"strings"
@@ -73,7 +74,23 @@ func main() {
 	}
 
 	defaultCfg := fetcher.DefaultConfig()
-	cmd := &cli.Command{
+	cmd := newRootCommand(defaultCfg)
+
+	if err := cmd.Run(context.Background(), routeToDefaultWeb(os.Args, cmd)); err != nil {
+		var exitErr *exitStatusError
+		if errors.As(err, &exitErr) {
+			if msg := strings.TrimSpace(exitErr.msg); msg != "" {
+				fmt.Fprintln(os.Stderr, msg)
+			}
+			os.Exit(exitErr.code)
+		}
+		// urfave/cli already prints usage/parse errors to ErrWriter by default.
+		os.Exit(1)
+	}
+}
+
+func newRootCommand(defaultCfg fetcher.Config) *cli.Command {
+	return &cli.Command{
 		Name:  "agent-fetch",
 		Usage: "Fetch web pages as clean Markdown for AI-agent workflows",
 		Description: "Extracts readable content from web pages and converts it to Markdown.\n" +
@@ -108,18 +125,6 @@ func main() {
 			return &exitStatusError{code: 2}
 		},
 	}
-
-	if err := cmd.Run(context.Background(), routeToDefaultWeb(os.Args)); err != nil {
-		var exitErr *exitStatusError
-		if errors.As(err, &exitErr) {
-			if msg := strings.TrimSpace(exitErr.msg); msg != "" {
-				fmt.Fprintln(os.Stderr, msg)
-			}
-			os.Exit(exitErr.code)
-		}
-		// urfave/cli already prints usage/parse errors to ErrWriter by default.
-		os.Exit(1)
-	}
 }
 
 func newWebCommand(defaultCfg fetcher.Config) *cli.Command {
@@ -240,7 +245,7 @@ func runWebFetch(ctx context.Context, c *cli.Command) error {
 	return nil
 }
 
-func routeToDefaultWeb(args []string) []string {
+func routeToDefaultWeb(args []string, root *cli.Command) []string {
 	if len(args) <= 1 {
 		return args
 	}
@@ -249,8 +254,13 @@ func routeToDefaultWeb(args []string) []string {
 	if first == "" {
 		return args
 	}
+
+	if root != nil && root.Command(first) != nil {
+		return args
+	}
+
 	switch first {
-	case webCommandName, "doctor", "help", "h", "--help", "-h", "--version", "-v":
+	case "help", "h", "--help", "-h", "--version", "-v":
 		return args
 	}
 
@@ -260,6 +270,20 @@ func routeToDefaultWeb(args []string) []string {
 	return rewritten
 }
 
+func runForTest(args []string, out, errOut io.Writer) error {
+	cli.VersionPrinter = func(cmd *cli.Command) {
+		w := cmd.Root().Writer
+		if w == nil {
+			w = os.Stdout
+		}
+		fmt.Fprintln(w, cmd.Version)
+	}
+	cmd := newRootCommand(fetcher.DefaultConfig())
+	cmd.Writer = out
+	cmd.ErrWriter = errOut
+	return cmd.Run(context.Background(), routeToDefaultWeb(args, cmd))
+}
+
 func parseHeaders(raw []string) (http.Header, error) {
 	h := make(http.Header)
 	for _, item := range raw {

cmd/agent-fetch/main_test.go

@@ -1,11 +1,18 @@
 package main
 
 import (
+	"context"
 	"reflect"
+	"strings"
 	"testing"
+
+	"github.com/firede/agent-fetch/internal/fetcher"
+	"github.com/urfave/cli/v3"
 )
 
 func TestRouteToDefaultWeb(t *testing.T) {
+	root := newRootCommand(fetcher.DefaultConfig())
+
 	tests := []struct {
 		name string
 		in   []string
@@ -46,14 +53,79 @@ func TestRouteToDefaultWeb(t *testing.T) {
 			in:   []string{"agent-fetch", "--version"},
 			want: []string{"agent-fetch", "--version"},
 		},
+		{
+			name: "unknown token treated as web shorthand",
+			in:   []string{"agent-fetch", "https://example.net"},
+			want: []string{"agent-fetch", "web", "https://example.net"},
+		},
 	}
 
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			got := routeToDefaultWeb(tc.in)
+			got := routeToDefaultWeb(tc.in, root)
 			if !reflect.DeepEqual(got, tc.want) {
 				t.Fatalf("unexpected args rewrite\ngot:  %#v\nwant: %#v", got, tc.want)
 			}
 		})
 	}
 }
+
+func TestRouteToDefaultWeb_RegisteredSubcommandUntouched(t *testing.T) {
+	root := newRootCommand(fetcher.DefaultConfig())
+	const testSubcommand = "__test_subcommand__"
+	root.Commands = append(root.Commands, &cli.Command{Name: testSubcommand})
+
+	in := []string{"agent-fetch", testSubcommand, "arg1"}
+	want := []string{"agent-fetch", testSubcommand, "arg1"}
+	got := routeToDefaultWeb(in, root)
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("unexpected args rewrite\ngot:  %#v\nwant: %#v", got, want)
+	}
+}
+
+func TestHelpOutputContracts(t *testing.T) {
+	t.Run("root help shows default web options", func(t *testing.T) {
+		var out strings.Builder
+		err := runForTest([]string{"agent-fetch", "-h"}, &out, &out)
+		if err != nil {
+			t.Fatalf("run help failed: %v", err)
+		}
+		helpText := out.String()
+		if !strings.Contains(helpText, "DEFAULT WEB OPTIONS:") {
+			t.Fatalf("expected default web options section, got:\n%s", helpText)
+		}
+		if !strings.Contains(helpText, "--format string") {
+			t.Fatalf("expected web options in root help, got:\n%s", helpText)
+		}
+	})
+
+	t.Run("doctor help excludes web flags", func(t *testing.T) {
+		var out strings.Builder
+		err := runForTest([]string{"agent-fetch", "doctor", "-h"}, &out, &out)
+		if err != nil {
+			t.Fatalf("run doctor help failed: %v", err)
+		}
+		helpText := out.String()
+		if !strings.Contains(helpText, "--browser-path string") {
+			t.Fatalf("expected doctor option in doctor help, got:\n%s", helpText)
+		}
+		if strings.Contains(helpText, "--format string") {
+			t.Fatalf("did not expect web flag in doctor help, got:\n%s", helpText)
+		}
+	})
+
+	t.Run("web help shows fetch flags", func(t *testing.T) {
+		cmd := newRootCommand(fetcher.DefaultConfig())
+		var out strings.Builder
+		cmd.Writer = &out
+		cmd.ErrWriter = &out
+		err := cmd.Run(context.Background(), routeToDefaultWeb([]string{"agent-fetch", "web", "-h"}, cmd))
+		if err != nil {
+			t.Fatalf("run web help failed: %v", err)
+		}
+		helpText := out.String()
+		if !strings.Contains(helpText, "--format string") {
+			t.Fatalf("expected fetch flag in web help, got:\n%s", helpText)
+		}
+	})
+}