chore: merge w main

Author: zimeg

.circleci/config.yml

@@ -113,7 +113,7 @@ jobs:
         default: "dev-build"
     docker: # run the steps with Docker
       # CircleCI Go images available at: https://hub.docker.com/r/circleci/golang/
-      - image: cimg/go:1.26.1
+      - image: cimg/go:1.26.2
     steps: # steps that comprise the `build` job
       - checkout # check out source code to working directory
       - restore_cache: # restores saved cache if no changes are detected since last run

.claude/settings.json

@@ -17,6 +17,7 @@
       "Bash(git log:*)",
       "Bash(git status:*)",
       "Bash(go build:*)",
+      "Bash(go doc:*)",
       "Bash(go mod graph:*)",
       "Bash(go mod tidy:*)",
       "Bash(go mod tidy:*)",

.github/STYLE_GUIDE.md

@@ -5,7 +5,9 @@ A current suggestion for how Slack CLI inputs are handled and outputs are format
 - **Input**
   - [Prompts are Flags with Forms](#prompts-are-flags-with-forms)
 - **Output**
-  - [Format Sections with Command Details](#format-sections-with-command-details)
+  - [Help Arguments use Opinionated Brackets](#help-arguments-use-opinionated-brackets)
+  - [Help Descriptions find Complete Sentences](#help-descriptions-find-complete-sentences)
+  - [Section Formats with Command Headings](#section-formats-with-command-headings)
 
 ## Input
 
@@ -23,7 +25,44 @@ A flag option should exist for each prompt with a form fallback. Either default
 
 Results of a command go toward informing current happenings and suggesting next steps.
 
-### Format Sections with Command Details
+### Help Arguments use Opinionated Brackets
+
+The square brackets surrounding command arguments hint that these are optional:
+
+```
+USAGE
+  $ slack env add [name] [value] [flags]
+```
+
+The angled brackets around arguments hint that these are required:
+
+```
+USAGE
+  $ slack <command>
+```
+
+Optional and required arguments can be mixed-and-matched:
+
+```
+USAGE
+  $ slack <command> [args] [flags]
+```
+
+These examples have meaningful argument placeholders and sometimes forms as fallback.
+
+### Help Descriptions find Complete Sentences
+
+The output of extended help descriptions should be complete sentences:
+
+```txt
+$ slack docs search --help
+Search the Slack developer docs and return results in text, JSON, or browser
+format.
+```
+
+This example uses punctuation and breaks lines at or before the 80 character count.
+
+### Section Formats with Command Headings
 
 A command often prints information and details about the process happenings. We format this as a section:
 

.github/workflows/e2e_tests.yml

@@ -22,7 +22,7 @@ jobs:
     steps:
       - name: Trigger CircleCI 'local' workflow
         if: ${{ github.event.inputs.status == 'false' }}
-        uses: promiseofcake/circleci-trigger-action@a72a9ff0b0c663613c13e47d53301ea55d7da5d9 # v3.0.1
+        uses: promiseofcake/circleci-trigger-action@e182462eba499cd888af8e3376038a2aeb58fa02 # v3.0.2
         with:
           user-token: ${{ secrets.CIRCLECI_TOKEN }}
           project-slug: slackapi/slack-cli
@@ -31,7 +31,7 @@ jobs:
           payload: '{"run_local_build_test_workflow": true}'
       - name: Trigger CircleCI 'e2e' workflow
         if: ${{ github.event.inputs.status == 'true' }}
-        uses: promiseofcake/circleci-trigger-action@a72a9ff0b0c663613c13e47d53301ea55d7da5d9 # v3.0.1
+        uses: promiseofcake/circleci-trigger-action@e182462eba499cd888af8e3376038a2aeb58fa02 # v3.0.2
         with:
           user-token: ${{ secrets.CIRCLECI_TOKEN }}
           project-slug: slackapi/slack-cli

.github/workflows/tests.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
-          go-version: "1.26.1"
+          go-version: "1.26.2"
       - name: Lint
         uses: golangci/golangci-lint-action@1e7e51e771db61008b38414a730f564565cf7c20 # v9.2.0
         with:
@@ -57,7 +57,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
-          go-version: "1.26.1"
+          go-version: "1.26.2"
       - name: Report health score
         uses: slackapi/slack-health-score@d58a419f15cdaff97e9aa7f09f95772830ab66f7 # v0.1.1
         with:

Makefile

@@ -84,6 +84,7 @@ tag:
 		exit 1; \
 	fi
 	@printf "$(FONT_BOLD)Updating Docs$(FONT_RESET)\n"
+	rm -rf ./docs/reference/commands ./docs/reference/errors.md
 	./bin/slack docgen ./docs/reference --skip-update
 	sed -i.bak -E "s#slack_cli_[0-9]+\.[0-9]+\.[0-9]+_macOS_arm64\.tar\.gz#slack_cli_$(RELEASE_VERSION)_macOS_arm64.tar.gz#" docs/guides/installing-the-slack-cli-for-mac-and-linux.md
 	sed -i.bak -E "s#slack_cli_[0-9]+\.[0-9]+\.[0-9]+_macOS_amd64\.tar\.gz#slack_cli_$(RELEASE_VERSION)_macOS_amd64.tar.gz#" docs/guides/installing-the-slack-cli-for-mac-and-linux.md

cmd/app/app.go

@@ -25,7 +25,7 @@ import (
 func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "app",
-		Aliases: []string{"workspace", "app", "apps", "team", "teams", "workspaces"},
+		Aliases: []string{"app", "apps"},
 		Short:   "Install, uninstall, and list teams with the app installed",
 		Long:    "Install, uninstall, and list teams with the app installed",
 		Example: style.ExampleCommandsf([]style.ExampleCommand{
@@ -45,20 +45,6 @@ func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runListCommand(cmd, clients)
 		},
-		PostRunE: func(cmd *cobra.Command, args []string) error {
-			ctx := cmd.Context()
-			// DEPRECATED(semver:major): remove the "workspace" alias
-			if cmd.CalledAs() == "workspace" {
-				clients.IO.PrintInfo(ctx, false,
-					"\n%s It looks like you used %s. This command will be deprecated in an upcoming release.\n    You can now use %s instead of %s.\n ",
-					style.Emoji("bulb"),
-					style.Commandf("workspace", true),
-					style.Commandf("app", true),
-					style.Commandf("workspace", true),
-				)
-			}
-			return nil
-		},
 	}
 
 	// Add child commands

cmd/app/app_test.go

@@ -24,7 +24,7 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-func TestWorkspaceCommand(t *testing.T) {
+func TestAppCommand(t *testing.T) {
 	// Create mocks
 	ctx := slackcontext.MockContext(t.Context())
 	clientsMock := shared.NewClientsMock()

cmd/docs/docs.go

@@ -15,101 +15,61 @@
 package docs
 
 import (
-	"fmt"
-	"net/url"
-	"strings"
-
 	"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
+const docsURL = "https://docs.slack.dev"
 
 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 them using the search subcommand",
 		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\"",
+				Command: "docs search \"Block Kit\"",
 			},
 			{
-				Meaning: "Open Slack docs search page",
-				Command: "docs --search",
+				Meaning: "Search docs and open results in browser",
+				Command: "docs search \"Block Kit\" --output=browser",
 			},
 		}),
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runDocsCommand(clients, cmd, args)
+			return runDocsCommand(clients, cmd)
 		},
+		// Disable automatic suggestions for unknown commands
+		DisableSuggestions: true,
 	}
 
-	cmd.Flags().BoolVar(&searchMode, "search", false, "open Slack docs search page or search with query")
+	// Add the search subcommand
+	cmd.AddCommand(NewSearchCommand(clients))
 
 	return cmd
 }
 
 // runDocsCommand opens Slack developer docs in the browser
-func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command, args []string) error {
+func runDocsCommand(clients *shared.ClientFactory, cmd *cobra.Command) 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") {
-		query := strings.Join(args, " ")
-		return slackerror.New(slackerror.ErrDocsSearchFlagRequired).WithRemediation(
-			"Use --search flag: %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"
-	}
-
 	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

@@ -27,7 +27,7 @@ import (
 
 func Test_Docs_DocsCommand(t *testing.T) {
 	testutil.TableTestCommand(t, testutil.CommandTests{
-		"opens docs homepage without search": {
+		"opens docs homepage": {
 			Setup: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock, cf *shared.ClientFactory) {
 			},
 			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
@@ -40,93 +40,9 @@ func Test_Docs_DocsCommand(t *testing.T) {
 				"https://docs.slack.dev",
 			},
 		},
-		"fails when positional argument provided without search flag": {
+		"rejects positional arguments": {
 			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": {
-			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"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				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=messaging",
-			},
-		},
-		"handles search with multiple arguments": {
-			CmdArgs: []string{"--search", "Block", "Kit", "Element"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				expectedURL := "https://docs.slack.dev/search/?q=Block+Kit+Element"
-				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",
-			},
-		},
-		"handles search query with multiple words": {
-			CmdArgs: []string{"--search", "socket mode"},
-			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)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=socket+mode",
-			},
-		},
-		"handles special characters in search query": {
-			CmdArgs: []string{"--search", "messages & webhooks"},
-			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)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=messages+%26+webhooks",
-			},
-		},
-		"handles search query with quotes": {
-			CmdArgs: []string{"--search", "webhook \"send message\""},
-			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)
-				cm.IO.AssertCalled(t, "PrintTrace", mock.Anything, slacktrace.DocsSearchSuccess, mock.Anything)
-			},
-			ExpectedOutputs: []string{
-				"Docs Search",
-				"https://docs.slack.dev/search/?q=webhook+%22send+message%22",
-			},
-		},
-		"handles search flag without argument": {
-			CmdArgs: []string{"--search"},
-			ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) {
-				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/",
-			},
+			ExpectedErrorStrings: []string{"unknown command"},
 		},
 	}, func(cf *shared.ClientFactory) *cobra.Command {
 		return NewCommand(cf)