Feat: Slack docs search sub command with JSON output

cmd/docs/docs.go

@@ -15,101 +15,178 @@
 package docs
 
 import (
+	"context"
+	"encoding/json"
 	"fmt"
 	"net/url"
 	"strings"
 
+	"github.com/slackapi/slack-cli/internal/search"
 	"github.com/slackapi/slack-cli/internal/shared"
 	"github.com/slackapi/slack-cli/internal/slackerror"
 	"github.com/slackapi/slack-cli/internal/slacktrace"
 	"github.com/slackapi/slack-cli/internal/style"
 	"github.com/spf13/cobra"
 )
 
-var searchMode bool
+var outputFormat string
+var searchLimit int
+var searchFilter string
 
 func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "docs",
 		Short: "Open Slack developer docs",
-		Long:  "Open the Slack developer docs in your browser, with optional search functionality",
+		Long:  "Open the Slack developer docs in your browser, or search docs with subcommands",
 		Example: style.ExampleCommandsf([]style.ExampleCommand{
 			{
 				Meaning: "Open Slack developer docs homepage",
 				Command: "docs",
 			},
 			{
-				Meaning: "Search Slack developer docs for Block Kit",
-				Command: "docs --search \"Block Kit\"",
+				Meaning: "Search and return JSON (default)",
+				Command: "docs search \"Block Kit\"",
 			},
 			{
-				Meaning: "Open Slack docs search page",
-				Command: "docs --search",
+				Meaning: "Search and open in browser",
+				Command: "docs search \"webhooks\" --output=browser",
 			},
 		}),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runDocsCommand(clients, cmd, args)
 		},
 	}
 
-	cmd.Flags().BoolVar(&searchMode, "search", false, "open Slack docs search page or search with query")
+	// Add search subcommand
+	cmd.AddCommand(newSearchCommand(clients))
 
 	return cmd
 }
 
+// newSearchCommand creates the search subcommand
+func newSearchCommand(clients *shared.ClientFactory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "search [query]",
+		Short: "Search Slack developer documentation",
+		Long:  "Search the Slack developer documentation and return results in JSON format (default) or open in browser. If no query provided, opens search page in browser.",
+		Args:  cobra.MaximumNArgs(1),
+		Example: style.ExampleCommandsf([]style.ExampleCommand{
+			{
+				Meaning: "Open docs search page in browser",
+				Command: "docs search",
+			},
+			{
+				Meaning: "Search for Block Kit (returns JSON by default)",
+				Command: "docs search \"Block Kit\"",
+			},
+			{
+				Meaning: "Search and open in browser",
+				Command: "docs search \"Block Kit\" --output=browser",
+			},
+			{
+				Meaning: "Search with custom limit",
+				Command: "docs search \"webhooks\" --limit=50",
+			},
+			{
+				Meaning: "Search with filter",
+				Command: "docs search \"webhooks\" --filter=guides",
+			},
+			{
+				Meaning: "Search Python documentation and open in browser",
+				Command: "docs search \"bolt\" --filter=python --output=browser",
+			},
+		}),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) == 0 {
+				return runSearchBrowserCommand(clients, cmd)
+			}
+			return runSearchCommand(clients, cmd, args[0])
+		},
+	}
+
+	cmd.Flags().StringVar(&outputFormat, "output", "json", "output format: json, browser")
+	cmd.Flags().IntVar(&searchLimit, "limit", 20, "maximum number of results to return")
+	cmd.Flags().StringVar(&searchFilter, "filter", "", "filter results by content type: guides, reference, changelog, python, javascript, java, slack_cli, slack_github_action, deno_slack_sdk")
+
+	return cmd
+}
+
+// openSearchInBrowser opens the docs search page in browser
+func openSearchInBrowser(clients *shared.ClientFactory, ctx context.Context, searchURL string) error {
+	clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
+		Emoji: "books",
+		Text:  "Docs Search",
+		Secondary: []string{
+			searchURL,
+		},
+	}))
+
+	clients.Browser().OpenURL(searchURL)
+	clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, "")
+	return nil
+}
+
+// runSearchBrowserCommand opens the docs search page in browser
+func runSearchBrowserCommand(clients *shared.ClientFactory, cmd *cobra.Command) error {
+	ctx := cmd.Context()
+	searchURL := "https://docs.slack.dev/search"
+	return openSearchInBrowser(clients, ctx, searchURL)
+}
+
+// runSearchCommand handles the search subcommand
+func runSearchCommand(clients *shared.ClientFactory, cmd *cobra.Command, query string) error {
+	ctx := cmd.Context()
+
+	results, err := search.SearchDocs(query, searchFilter, searchLimit)
+	if err != nil {
+		return fmt.Errorf("search failed: %w", err)
+	}
+
+	// Output results
+	if outputFormat == "json" {
+		jsonBytes, err := json.MarshalIndent(results, "", "  ")
+		if err != nil {
+			return fmt.Errorf("failed to encode JSON: %w", err)
+		}
+		fmt.Println(string(jsonBytes))
+	} else {
+		// Browser output - open search page with query
+		searchURL := fmt.Sprintf("https://docs.slack.dev/search/?q=%s", url.QueryEscape(query))
+		if searchFilter != "" {
+			searchURL += fmt.Sprintf("&filter=%s", url.QueryEscape(searchFilter))
+		}
+		return openSearchInBrowser(clients, ctx, searchURL)
+	}
+
+	return nil
+}
+
 // runDocsCommand opens Slack developer docs in the browser
 func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string) error {
 	ctx := cmd.Context()
 
-	var docsURL string
-	var sectionText string
-
-	// Validate: if there are arguments, --search flag must be used
-	if len(args) > 0 && !cmd.Flags().Changed("search") {
+	// If any arguments provided, suggest using search subcommand
+	if len(args) > 0 {
 		query := strings.Join(args, " ")
 		return slackerror.New(slackerror.ErrDocsSearchFlagRequired).WithRemediation(
-			"Use --search flag: %s",
-			style.Commandf(fmt.Sprintf("docs --search \"%s\"", query), false),
+			"Use search subcommand: %s",
+			style.Commandf(fmt.Sprintf("docs search \"%s\"", query), false),
 		)
 	}
 
-	if cmd.Flags().Changed("search") {
-		if len(args) > 0 {
-			// --search "query" (space-separated) - join all args as the query
-			query := strings.Join(args, " ")
-			encodedQuery := url.QueryEscape(query)
-			docsURL = fmt.Sprintf("https://docs.slack.dev/search/?q=%s", encodedQuery)
-			sectionText = "Docs Search"
-		} else {
-			// --search (no argument) - open search page
-			docsURL = "https://docs.slack.dev/search/"
-			sectionText = "Docs Search"
-		}
-	} else {
-		// No search flag: default homepage
-		docsURL = "https://docs.slack.dev"
-		sectionText = "Docs Open"
-	}
+	// Open docs homepage
+	docsURL := "https://docs.slack.dev"
 
 	clients.IO.PrintInfo(ctx, false, "\n%s", style.Sectionf(style.TextSection{
 		Emoji: "books",
-		Text:  sectionText,
+		Text:  "Docs Open",
 		Secondary: []string{
 			docsURL,
 		},
 	}))
 
 	clients.Browser().OpenURL(docsURL)
-
-	if cmd.Flags().Changed("search") {
-		traceValue := ""
-		if len(args) > 0 {
-			traceValue = strings.Join(args, " ")
-		}
-		clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, traceValue)
-	} else {
-		clients.IO.PrintTrace(ctx, slacktrace.DocsSuccess)
-	}
+	clients.IO.PrintTrace(ctx, slacktrace.DocsSuccess)
 
 	return nil
 }

cmd/docs/docs_test.go

@@ -40,48 +40,55 @@ func Test_Docs_DocsCommand(t *testing.T) {
 				"https://docs.slack.dev",
 			},
 		},
-		"fails when positional argument provided without search flag": {
+		"fails when positional argument provided without search subcommand": {
 			CmdArgs:              []string{"Block Kit"},
 			ExpectedErrorStrings: []string{"Invalid docs command. Did you mean to search?"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
 				// No browser calls should be made when command fails
 				cm.Browser.AssertNotCalled(t, "OpenURL")
 			},
 		},
-		"fails when multiple positional arguments provided without search flag": {
+		"fails when multiple positional arguments provided without search subcommand": {
 			CmdArgs:              []string{"webhook", "send", "message"},
 			ExpectedErrorStrings: []string{"Invalid docs command. Did you mean to search?"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
 				// No browser calls should be made when command fails
 				cm.Browser.AssertNotCalled(t, "OpenURL")
 			},
 		},
-		"opens docs with search query using space syntax": {
-			CmdArgs: []string{"--search", "messaging"},
+	}, func(cf *shared.ClientFactory) *cobra.Command {
+		return NewCommand(cf)
+	})
+}
+
+func Test_Docs_SearchSubcommand(t *testing.T) {
+	testutil.TableTestCommand(t, testutil.CommandTests{
+		"opens search page without query": {
+			CmdArgs: []string{"search"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=messaging"
+				expectedURL := "https://docs.slack.dev/search"
 				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
 				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
 			},
 			ExpectedOutputs: []string{
 				"Docs Search",
-				"https://docs.slack.dev/search/?q=messaging",
+				"https://docs.slack.dev/search",
 			},
 		},
-		"handles search with multiple arguments": {
-			CmdArgs: []string{"--search", "Block", "Kit", "Element"},
+		"opens search page with query in browser mode": {
+			CmdArgs: []string{"search", "messaging", "--output=browser"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=Block+Kit+Element"
+				expectedURL := "https://docs.slack.dev/search/?q=messaging"
 				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
 				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
 			},
 			ExpectedOutputs: []string{
 				"Docs Search",
-				"https://docs.slack.dev/search/?q=Block+Kit+Element",
+				"https://docs.slack.dev/search/?q=messaging",
 			},
 		},
-		"handles search query with multiple words": {
-			CmdArgs: []string{"--search", "socket mode"},
+		"handles search query with multiple words in browser mode": {
+			CmdArgs: []string{"search", "socket mode", "--output=browser"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
 				expectedURL := "https://docs.slack.dev/search/?q=socket+mode"
 				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
@@ -92,8 +99,8 @@ func Test_Docs_DocsCommand(t *testing.T) {
 				"https://docs.slack.dev/search/?q=socket+mode",
 			},
 		},
-		"handles special characters in search query": {
-			CmdArgs: []string{"--search", "messages & webhooks"},
+		"handles special characters in search query in browser mode": {
+			CmdArgs: []string{"search", "messages & webhooks", "--output=browser"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
 				expectedURL := "https://docs.slack.dev/search/?q=messages+%26+webhooks"
 				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
@@ -104,8 +111,8 @@ func Test_Docs_DocsCommand(t *testing.T) {
 				"https://docs.slack.dev/search/?q=messages+%26+webhooks",
 			},
 		},
-		"handles search query with quotes": {
-			CmdArgs: []string{"--search", "webhook \"send message\""},
+		"handles search query with quotes in browser mode": {
+			CmdArgs: []string{"search", "webhook \"send message\"", "--output=browser"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
 				expectedURL := "https://docs.slack.dev/search/?q=webhook+%22send+message%22"
 				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
@@ -116,16 +123,16 @@ func Test_Docs_DocsCommand(t *testing.T) {
 				"https://docs.slack.dev/search/?q=webhook+%22send+message%22",
 			},
 		},
-		"handles search flag without argument": {
-			CmdArgs: []string{"--search"},
+		"handles search with filter in browser mode": {
+			CmdArgs: []string{"search", "webhooks", "--filter=guides", "--output=browser"},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/"
+				expectedURL := "https://docs.slack.dev/search/?q=webhooks&filter=guides"
 				cm.Browser.AssertCalled(t, "OpenURL", expectedURL)
 				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
 			},
 			ExpectedOutputs: []string{
 				"Docs Search",
-				"https://docs.slack.dev/search/",
+				"https://docs.slack.dev/search/?q=webhooks&filter=guides",
 			},
 		},
 	}, func(cf *shared.ClientFactory) *cobra.Command {