streamline

Author: lukegalbraithrussell

cmd/docs/docs.go

@@ -19,7 +19,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/url"
-	"path/filepath"
 	"strings"
 
 	"github.com/slackapi/slack-cli/internal/search"
@@ -30,192 +29,164 @@ import (
 	"github.com/spf13/cobra"
 )
 
-var searchMode bool
 var outputFormat string
 var searchLimit int
-var searchOffset 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: "Search and get JSON results",
-				Command: "docs --search \"Block Kit\" --output=json",
+				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)
+		},
+	}
+
+	// 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 \"Block Kit\" --output=json --limit=50",
+				Command: "docs search \"webhooks\" --limit=50",
 			},
 			{
-				Meaning: "Search with pagination",
-				Command: "docs --search \"Block Kit\" --output=json --limit=20 --offset=20",
+				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 {
-			return runDocsCommand(clients, cmd, args)
+			if len(args) == 0 {
+				return runSearchBrowserCommand(clients, cmd)
+			}
+			return runSearchCommand(clients, cmd, args[0])
 		},
 	}
 
-	cmd.Flags().BoolVar(&searchMode, "search", false, "search Slack docs with optional query")
-	cmd.Flags().StringVar(&outputFormat, "output", "browser", "output format: browser, json")
+	cmd.Flags().StringVar(&outputFormat, "output", "json", "output format: json, browser")
 	cmd.Flags().IntVar(&searchLimit, "limit", 20, "maximum number of results to return")
-	cmd.Flags().IntVar(&searchOffset, "offset", 0, "number of results to skip (for pagination)")
+	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
 }
 
-// DocsOutput represents the structured output for --json mode
-type DocsOutput struct {
-	URL   string `json:"url"`
-	Query string `json:"query,omitempty"`
-	Type  string `json:"type"` // "homepage", "search", or "search_with_query"
-}
-
-// ProgrammaticSearchOutput represents the output from local docs search
-type ProgrammaticSearchOutput = search.SearchResponse
+// 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,
+		},
+	}))
 
-// findDocsRepo tries to locate the docs repository
-func findDocsRepo() string {
-	return search.FindDocsRepo()
+	clients.Browser().OpenURL(searchURL)
+	clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, "")
+	return nil
 }
 
-// runProgrammaticSearch executes the local search
-func runProgrammaticSearch(query string, docsPath string) (*ProgrammaticSearchOutput, error) {
-	contentDir := filepath.Join(docsPath, "content")
-	return search.SearchDocs(query, "", searchLimit, searchOffset, contentDir)
+// 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)
 }
 
-// runDocsCommand opens Slack developer docs in the browser or performs programmatic search
-func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string) error {
+// runSearchCommand handles the search subcommand
+func runSearchCommand(clients *shared.ClientFactory, cmd *cobra.Command, query string) error {
 	ctx := cmd.Context()
 
-	var docsURL string
-	var sectionText string
-	var query string
-	var docType string
-
-	// Validate: if there are arguments, --search flag must be used
-	if len(args) > 0 && !cmd.Flags().Changed("search") {
-		query := strings.Join(args, " ")
-		return slackerror.New(slackerror.ErrDocsSearchFlagRequired).WithRemediation(
-			"Use --search flag: %s",
-			style.Commandf(fmt.Sprintf("docs --search \"%s\"", query), false),
-		)
+	results, err := search.SearchDocs(query, searchFilter, searchLimit)
+	if err != nil {
+		return fmt.Errorf("search failed: %w", err)
 	}
 
-	if cmd.Flags().Changed("search") {
-		if len(args) > 0 {
-			query = strings.Join(args, " ")
-
-			// Check output format
-			if outputFormat == "json" {
-				return runProgrammaticSearchCommand(clients, ctx, query)
-			}
-
-			// Default browser search
-			encodedQuery := url.QueryEscape(query)
-			docsURL = fmt.Sprintf("https://docs.slack.dev/search/?q=%s", encodedQuery)
-			sectionText = "Docs Search"
-			docType = "search_with_query"
-		} else {
-			// --search (no argument) - open search page
-			docsURL = "https://docs.slack.dev/search/"
-			sectionText = "Docs Search"
-			docType = "search"
+	// 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 {
-		// No search flag: default homepage
-		docsURL = "https://docs.slack.dev"
-		sectionText = "Docs Open"
-		docType = "homepage"
-	}
-
-	// Handle JSON output mode (for browser-based results only)
-	if outputFormat == "json" && !cmd.Flags().Changed("search") {
-		output := DocsOutput{
-			URL:   docsURL,
-			Query: query,
-			Type:  docType,
-		}
-
-		jsonBytes, err := json.MarshalIndent(output, "", "  ")
-		if err != nil {
-			return slackerror.New(slackerror.ErrDocsJSONEncodeFailed)
+		// 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)
+	}
 
-		fmt.Println(string(jsonBytes))
+	return nil
+}
 
-		// Still print trace for analytics
-		if cmd.Flags().Changed("search") {
-			traceValue := query
-			clients.IO.PrintTrace(ctx, slacktrace.DocsSearchSuccess, traceValue)
-		} else {
-			clients.IO.PrintTrace(ctx, slacktrace.DocsSuccess)
-		}
+// runDocsCommand opens Slack developer docs in the browser
+func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
 
-		return nil
+	// If any arguments provided, suggest using search subcommand
+	if len(args) > 0 {
+		query := strings.Join(args, " ")
+		return slackerror.New(slackerror.ErrDocsSearchFlagRequired).WithRemediation(
+			"Use search subcommand: %s",
+			style.Commandf(fmt.Sprintf("docs search \"%s\"", query), false),
+		)
 	}
 
-	// Standard browser-opening mode
+	// 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)
+	clients.IO.PrintTrace(ctx, slacktrace.DocsSuccess)
 
-	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)
-	}
-
-	return nil
-}
-
-// runProgrammaticSearchCommand handles local documentation search
-func runProgrammaticSearchCommand(clients *shared.ClientFactory, ctx context.Context, query string) error {
-	// Find the docs repository
-	docsPath := findDocsRepo()
-	if docsPath == "" {
-		clients.IO.PrintError(ctx, "❌ Docs repository not found")
-		clients.IO.PrintInfo(ctx, false, "💡 Make sure the docs repository is cloned alongside slack-cli")
-		clients.IO.PrintInfo(ctx, false, "   Expected structure:")
-		clients.IO.PrintInfo(ctx, false, "   ├── slack-cli/")
-		clients.IO.PrintInfo(ctx, false, "   └── docs/")
-		return fmt.Errorf("docs repository not found")
-	}
-
-	// Run the search
-	results, err := runProgrammaticSearch(query, docsPath)
-	if err != nil {
-		clients.IO.PrintError(ctx, "❌ Search failed: %v", err)
-		return err
-	}
-
-	// Always output JSON for programmatic search
-	jsonBytes, err := json.MarshalIndent(results, "", "  ")
-	if err != nil {
-		return fmt.Errorf("failed to encode JSON: %w", err)
-	}
-	fmt.Println(string(jsonBytes))
 	return nil
 }

go.mod

@@ -5,7 +5,6 @@ go 1.26.0
 require (
 	github.com/AlecAivazis/survey/v2 v2.3.7
 	github.com/briandowns/spinner v1.23.2
-	github.com/charmbracelet/bubbles v1.0.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/huh v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.0
@@ -43,6 +42,7 @@ require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/chainguard-dev/git-urls v1.0.2 // indirect
+	github.com/charmbracelet/bubbles v1.0.0 // indirect
 	github.com/charmbracelet/colorprofile v0.4.2 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
 	github.com/charmbracelet/x/exp/strings v0.1.0 // indirect
@@ -95,6 +95,6 @@ require (
 	github.com/stretchr/objx v0.5.3 // indirect
 	github.com/uber/jaeger-lib v2.4.1+incompatible // indirect
 	go.uber.org/atomic v1.11.0 // indirect
-	golang.org/x/term v0.40.0 // indirect
+	golang.org/x/term v0.40.0
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )