feat: add slack docs search subcommand

[lukegalbraithrussell]

Changelog

Adds slack docs search subcommand. It can output search results as JSON

Summary

slack docs search

Option	Type	Default	Description	Required
<query>	string		Search terms	Required
--output	string	text	Output format: text' , 'browser or json	Optional
--limit	int	20	Max number of results to return (JSON and text output only)	Optional

Examples

# Search and return JSON results
$ slack-cli docs search "Block Kit"

# Search and return JSON results with custom result limit
$ slack-cli docs search "api" --limit=5

# Search and open results in browser
$ slack-cli docs search "webhooks" --output=browser

Code coverage notes

The following lines in search.go have incomplete test coverage. They seemed cumbersome to cover.
(Summarized by Claude)

• Lines 88-89 (if cfg.output == "json" branch): Conditional routing logic that's difficult to test through the command framework. The actual JSON output logic is thoroughly tested via direct function calls.

• Lines 129-130 (JSON encoding error handling): Defensive error handling for an unrealistic scenario (broken pipe when piping output). Most CLI tools don't explicitly handle this edge case.

Requirements

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.47%. Comparing base (0c37128) to head (47613d0).

Files with missing lines	Patch %	Lines
cmd/docs/search.go	89.33%	6 Missing and 2 partials ⚠️
internal/api/docs.go	90.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #433      +/-   ##
==========================================
+ Coverage   70.32%   70.47%   +0.14%     
==========================================
  Files         220      222       +2     
  Lines       18506    18605      +99     
==========================================
+ Hits        13015    13111      +96     
- Misses       4313     4314       +1     
- Partials     1178     1180       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[lukegalbraithrussell]

This will be updated to docs.slack.dev once api endpoint PR is merged in private docs repo

[zimeg]

Suggested change

	const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"
	const docsURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/"

🪬 suggestion: We might want to abstract this to the docs/docs.go file since we target it in multiple places? It might be useful for testing changes too?

[srtaalej]

left some comments about terminal ouput and tests but these changes are looking really good ⭐ ! lets get those addressed so we can merge 😝

[srtaalej]

it'd be nice if URLs were full https://docs.slack.dev URLs so they're cmd+clickable in the terminal

{
      "url": "https://docs.slack.dev/block-kit/",
      "title": "Block Kit"
    },

right now the json outputs as

 {
      "url": "/block-kit/",
      "title": "Block Kit"
    },

[zimeg]

📚 thought: I agree listing entire links is ideal and might suggest we add a text format with this?

$ slack docs search "Block Kit" --output=text

👾 ramble: If this format is supported it seems awkward to write that flag instead of defaulting to it but this is personal preference I think!

[zimeg]

@lukegalbraithrussell This is an awesome feature to be bringing 📚 ✨

I'm leaving a handful of comments that do request changes, but I'm hoping we can work through these:

• The API method logic is included with command: I understand we reach a different host but we might still find api package useful.
• Defaulting outputs for the person reading: I'm a fan of JSON but find this jarring when hoping for a quick search in terminal. I instead suggest a default text output to use section formatting:

$ slack docs search "Block Kit"

• Deprecating the "--search" flag: Can we make this a separate PR? Adding JSON outputs might be blocking this PR from merging now, but I think those changes have a faster review 🏁
• Standardizing the docs.slack.dev API client: We're starting to find the same URL in multiple places and I'm hoping changes toward a standard place for this has good pattern?
• Erroring for unexpected inputs: One comment also notes that we should error instead of opening browsers for unexpected output types 👻

Please do let me know if I can share more toward these changes. I'd love to see this land 💌

[zimeg]

Suggested change

	cmd.Flags().BoolVar(&searchMode, "search", false, "[DEPRECATED] open Slack docs search page or search with query (use 'docs search' subcommand instead)")
	// DEPRECATED(semver:major): Remove in favor of "search" command
	cmd.Flags().BoolVar(&searchMode, "search", false, "open Slack docs search page or search with query")
	cmd.Flag("search").Hidden = true

🔭 suggestion: Let's prefer to hide deprecated features!

[zimeg]

📚 thought: I agree listing entire links is ideal and might suggest we add a text format with this?

$ slack docs search "Block Kit" --output=text

👾 ramble: If this format is supported it seems awkward to write that flag instead of defaulting to it but this is personal preference I think!

[zimeg]

Suggested change

	const docsSearchAPIURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/api/search"
	const docsURL = "https://docs-slack-d-search-api-duu9zr.herokuapp.com/"

🪬 suggestion: We might want to abstract this to the docs/docs.go file since we target it in multiple places? It might be useful for testing changes too?