feat: Add --category flag to docs search command#603
feat: Add --category flag to docs search command#603lukegalbraithrussell wants to merge 1 commit into
Conversation
Add a --category flag to `slack docs search` so results can be filtered by category, matching the filters offered by the docs site search modal: guides, reference, changelog, python, javascript, java, slack_cli, slack_github_action, deno_slack_sdk. - internal/api: thread category through DocsSearch, the DocsClient interface, the URL builder (appends &category= when set), and the mock. Add DocsSearchCategories as the shared source of valid values. - cmd/docs: add the --category flag, validate it against DocsSearchCategories (like --output), and pass it to the API for text and json output. For browser output, append &filter= to the search page URL for parity with the site. An empty category preserves the existing search-everything behavior. Docs reference regeneration (slack docgen) happens at release, not here. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #603 +/- ##
==========================================
+ Coverage 71.64% 71.67% +0.03%
==========================================
Files 226 226
Lines 19176 19191 +15
==========================================
+ Hits 13739 13756 +17
- Misses 4222 4223 +1
+ Partials 1215 1212 -3 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
zimeg
added
enhancement
zimeg
left a comment
zimeg
left a comment
There was a problem hiding this comment.
@lukegalbraithrussell Immense thanks for patient review of a feature we sought 🔍 ✨
I'm leaving approval with LGTM and good testing but am curious to loosen the checks of valid and invalid categories. We can revisit that whenever but are wanting to avoid needing ongoing updates to keep these flag values current 🏁
Most comments are rambles around that point so I apologize for self references of scattered ideas.
| // DocsSearchCategories lists the categories the docs search endpoint accepts, | ||
| // mirroring the filters offered by the docs site search modal. An empty | ||
| // category searches across all content. | ||
| var DocsSearchCategories = []string{ | ||
| "guides", | ||
| "reference", | ||
| "changelog", | ||
| "python", | ||
| "javascript", | ||
| "java", | ||
| "slack_cli", | ||
| "slack_github_action", | ||
| "deno_slack_sdk", | ||
| } |
There was a problem hiding this comment.
🪓 thought: I'd favor removing checks for categories from the CLI to leave as API validation instead. Either zero results returned or an error of some kind?
🌲 ramble: I'm suggesting this to avoid incompatible CLI versions with iterations of search - adding a new category to docs would require releasing and updating to unlock that which is somewhat inconvenient...
| if cfg.category != "" && !slices.Contains(api.DocsSearchCategories, cfg.category) { | ||
| return slackerror.New(slackerror.ErrInvalidFlag).WithMessage( | ||
| "Invalid category: %s", cfg.category, | ||
| ).WithRemediation( | ||
| "Use one of: %s", strings.Join(api.DocsSearchCategories, ", "), | ||
| ) | ||
| } |
There was a problem hiding this comment.
🗣️ note: Related to less validation within the CLI - if checking categories remains meaningful I'd favor either a warning output for unexpected values or an option to use --force as a workaround.
| Long: strings.Join([]string{ | ||
| "Search the Slack developer docs and return results in text, JSON, or browser", | ||
| "format.", | ||
| }, "\n"), |
There was a problem hiding this comment.
📚 suggestion: Including a list of available categories here might be useful in running commands?
| Emoji: "books", | ||
| Text: "Docs Search", | ||
| Secondary: []string{ | ||
| fmt.Sprintf("Displaying first %d of %d results for \"%s\"", len(searchResponse.Results), searchResponse.TotalResults, query), |
There was a problem hiding this comment.
| fmt.Sprintf("Displaying first %d of %d results for \"%s\" in %s", len(searchResponse.Results), searchResponse.TotalResults, query, category), |
🔭 thought: Also related to invalid categories, I wonder if including the search category here might be useful? And or in the section with zero results too?
2 participants
What
Adds a
--categoryflag toslack docs searchso results can be filtered by category:The docs site search modal lets you filter by category (Guides, Reference, Changelog, the SDK/library docs, etc.), and the
/api/v1/searchendpoint the CLI calls now supports acategoryparam (see slackapi/docs#634). This brings the CLI to parity with both.Categories
The 9 valid categories match the docs search endpoint / site modal:
guides,reference,changelog,python,javascript,java,slack_cli,slack_github_action,deno_slack_sdkChanges
internal/api/docs.go— threadcategorythroughDocsSearch, theDocsClientinterface, andbuildDocsSearchURL(appends&category=only when set). AddedDocsSearchCategoriesas the single source of truth for valid values.internal/api/api_mock.go— updated mock signature.cmd/docs/search.go— added the--categoryflag, validated againstDocsSearchCategories(same pattern as--output), passed to the API fortext/jsonoutput. Forbrowseroutput, appends&filter=<category>to the search page URL so the opened page matches.An empty
--category(the default) preserves the current search-everything behavior, so this is backward-compatible.Note
The generated command reference (
docs/reference/commands/slack_docs_search.md) is intentionally not included —slack docgenruns at release time, not per-PR.🤖 Generated with Claude Code