feat: add support for user-doc-based help routing + manifest generation

Author: robertolopezlopez

CONTRIBUTING.md

@@ -280,6 +280,33 @@ User-facing documentation is [available on GitBook](https://docs.snyk.io/feature
 `snyk help` output must also be [edited on GitBook](https://docs.snyk.io/features/snyk-cli/commands). Changes will
 automatically be pulled into Snyk CLI as pull requests.
 
+### CLI help command files (`help/cli-commands`)
+
+The Go CLI reads user-facing command help from markdown files under `help/cli-commands/`. These files are synced from
+GitBook into this repository (see the `sync-cli-help-to-user-docs` workflow). At build time, the CLI embeds a manifest
+of available help files (`cliv2/pkg/helpdocs/manifest.txt`) and uses it to decide whether to show legacy GitBook help
+or native Cobra help for a given command.
+
+When you add, remove, or rename files in `help/cli-commands/`, regenerate the manifest and commit the result:
+
+```sh
+make -C cliv2 helpdocs-manifest
+git add cliv2/pkg/helpdocs/manifest.txt
+```
+
+`make -C cliv2 test` and `make build` run this target automatically, but you still need to commit the updated
+`manifest.txt` when it changes. Go tests in `cliv2/pkg/helpdocs` verify that the manifest stays in sync with
+`help/cli-commands/`.
+
+To test help routing locally after building:
+
+```sh
+./binary-releases/snyk-macos-arm64 help test          # documented command → GitBook help
+./binary-releases/snyk-macos-arm64 help agent-scan    # undocumented command → Cobra help
+```
+
+Adjust the binary path for your platform (see [Building](#building)).
+
 ## Creating a branch
 
 Create a new branch before making any changes. Make sure to give it a descriptive name so that you can find it later.

cliv2/Makefile

@@ -126,6 +126,9 @@ HASH_STRING = $(HASH)$(HASH_ALGORITHM)
 SIGN_SCRIPT = $(WORKING_DIR)/scripts/sign_$(_GO_OS).sh
 ISSIGNED_SCRIPT = $(WORKING_DIR)/scripts/issigned_$(_GO_OS).sh
 EMBEDDED_DATA_DIR = $(WORKING_DIR)/internal/embedded/_data
+HELPDOCS_DIR = $(WORKING_DIR)/pkg/helpdocs
+HELPDOCS_MANIFEST = $(HELPDOCS_DIR)/manifest.txt
+HELPDOCS_SOURCE = $(WORKING_DIR)/../help/cli-commands/*.md
 
 ifeq ($(GOHOSTOS), windows)
 	SPECIAL_SHELL = powershell
@@ -188,7 +191,17 @@ summary:
 .PHONY: configure
 configure: _validate-build-mode summary $(CACHE_DIR) $(CACHE_DIR)/variables.mk $(V1_DIRECTORY)/$(V1_EMBEDDED_FILE_OUTPUT) dependencies $(CACHE_DIR)/prepare-3rd-party-licenses
 
-$(BUILD_DIR)/$(V2_EXECUTABLE_NAME): $(BUILD_DIR) $(SRCS) generate-ls-protocol-metadata
+.PHONY: helpdocs-manifest
+helpdocs-manifest:
+	@set -e; \
+	md_count=$$(ls $(HELPDOCS_SOURCE) 2>/dev/null | wc -l | tr -d ' '); \
+	if [ "$$md_count" -eq 0 ]; then \
+		echo "$(LOG_PREFIX) ERROR: no .md files found in help/cli-commands ($(HELPDOCS_SOURCE))"; \
+		exit 1; \
+	fi; \
+	ls $(HELPDOCS_SOURCE) | xargs -n1 basename | sort > $(HELPDOCS_MANIFEST)
+
+$(BUILD_DIR)/$(V2_EXECUTABLE_NAME): $(BUILD_DIR) $(SRCS) generate-ls-protocol-metadata $(HELPDOCS_MANIFEST)
 	$(eval LS_PROTOCOL_VERSION := $(shell cat $(LS_PROTOCOL_VERSION_FILE)))
 	$(eval LS_COMMIT_HASH := $(shell cat $(LS_COMMIT_HASH_FILE)))
 	$(eval EXTRA_FLAGS := -X github.com/snyk/snyk-ls/application/config.Version=$(LS_COMMIT_HASH) -X github.com/snyk/snyk-ls/application/config.LsProtocolVersion=$(LS_PROTOCOL_VERSION)  -X github.com/snyk/cli/cliv2/pkg/core.internalOS=$(GOOS) -X github.com/snyk/cli/cliv2/internal/embedded/cliv1.snykCLIVersion=$(CLI_V1_VERSION_TAG) -X github.com/snyk/cli-extension-iac/internal/commands/iactest.internalRulesClientURL=$(IAC_RULES_URL) -X github.com/snyk/cli/cliv2/internal/constants.StaticNodeJsBinary=$(STATIC_NODE_BINARY))
@@ -247,7 +260,7 @@ openboxtest:
 	@$(GOCMD) test -cover ./...
 
 .PHONY: test
-test: openboxtest
+test: helpdocs-manifest openboxtest
 
 .PHONY: lint
 lint: $(TOOLS_BIN)/golangci-lint

cliv2/pkg/core/main.go

@@ -50,6 +50,7 @@ import (
 
 	cli_errors "github.com/snyk/cli/cliv2/internal/errors"
 	"github.com/snyk/cli/cliv2/pkg/basic_workflows"
+	"github.com/snyk/cli/cliv2/pkg/helprouting"
 )
 
 // Option configures the CLI runner.
@@ -225,13 +226,6 @@ func runWorkflowAndProcessData(ctx context.Context, engine workflow.Engine, logg
 	return err
 }
 
-func help(_ *cobra.Command, _ []string) error {
-	helpProvided = true
-	args := utils.RemoveSimilar(os.Args[1:], "--") // remove all double dash arguments to avoid issues with the help command
-	args = append(args, "--help")
-	return defaultCmd(args)
-}
-
 func defaultCmd(args []string) error {
 	inputDirectory := cliv2.DetermineInputDirectory(args)
 	if len(inputDirectory) > 0 {
@@ -247,6 +241,11 @@ func defaultCmd(args []string) error {
 	return err
 }
 
+func runLegacyHelp() error {
+	filteredArgs := utils.RemoveSimilar(os.Args[1:], "--")
+	return defaultCmd(append(filteredArgs, "--help"))
+}
+
 func runTestCommandWithSarifEqualJson(cmd *cobra.Command, args []string, templateFiles []string) error {
 	// ensure legacy behavior, where sarif and json can be used interchangeably
 	globalConfiguration.AddAlternativeKeys(output_workflow.OUTPUT_CONFIG_KEY_SARIF, []string{output_workflow.OUTPUT_CONFIG_KEY_JSON})
@@ -378,19 +377,21 @@ func createCommandsForWorkflows(rootCommand *cobra.Command, engine workflow.Engi
 	}
 }
 
-func prepareRootCommand() *cobra.Command {
+func prepareRootCommand(router *helprouting.Router) *cobra.Command {
 	rootCommand := cobra.Command{
 		Use: "snyk",
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return defaultCmd(os.Args[1:])
 		},
 	}
 
-	// help for all commands is handled by the legacy cli
-	// TODO: discuss how to move help to extensions
+	// Help precedence: synced user-doc Markdown (legacy CLI) when available; otherwise Cobra help.
+	root := &rootCommand
 	helpCommand := cobra.Command{
-		Use:  "help",
-		RunE: help,
+		Use: "help",
+		RunE: func(c *cobra.Command, _ []string) error {
+			return router.Help(c, root, os.Args[1:])
+		},
 	}
 
 	// some static/global cobra configuration
@@ -399,8 +400,7 @@ func prepareRootCommand() *cobra.Command {
 	rootCommand.SilenceUsage = true
 	rootCommand.FParseErrWhitelist.UnknownFlags = true
 
-	// ensure that help and usage information comes from the legacy cli instead of cobra's default help
-	rootCommand.SetHelpFunc(func(c *cobra.Command, args []string) { _ = help(c, args) })
+	rootCommand.SetHelpFunc(func(c *cobra.Command, _ []string) { _ = router.Help(c, root, os.Args[1:]) })
 	rootCommand.SetHelpCommand(&helpCommand)
 	rootCommand.PersistentFlags().AddFlagSet(getGlobalFLags())
 
@@ -427,7 +427,7 @@ func handleError(err error) HandleError {
 		if commandError {
 			resultError = handleErrorFallbackToLegacyCLI
 		} else if flagError {
-			// handle flag errors explicitly since we need to delegate the help to the legacy CLI. This includes disabling the cobra default help/usage
+			// handle flag errors explicitly via help(): user-doc markdown when available, otherwise Cobra help
 			resultError = handleErrorShowHelp
 		}
 	}
@@ -464,16 +464,16 @@ func displayError(err error, userInterface ui.UserInterface, config configuratio
 }
 
 func handleRetryNotification(engine workflow.Engine, logger *zerolog.Logger, err error) {
-	if ui := engine.GetUserInterface(); ui != nil {
-		if outputErr := ui.OutputError(err); outputErr != nil {
+	if userInterface := engine.GetUserInterface(); userInterface != nil {
+		if outputErr := userInterface.OutputError(err); outputErr != nil {
 			logger.Warn().Err(outputErr).Msg("failed to show rate-limit retry warning")
 		}
 	} else {
 		logger.Warn().Msg("rate-limit retry warning not shown: user interface not attached")
 	}
 
-	if analytics := engine.GetAnalytics(); analytics != nil {
-		analytics.AddError(err)
+	if engineAnalytics := engine.GetAnalytics(); engineAnalytics != nil {
+		engineAnalytics.AddError(err)
 	} else {
 		logger.Warn().Msg("rate-limit retry not recorded in analytics: collector not initialized")
 	}
@@ -543,7 +543,11 @@ func mainWithErrorCode(additionalExts []workflow.ExtensionInit) int {
 	var err error
 	rInfo := runtimeinfo.New(runtimeinfo.WithName("snyk-cli"), runtimeinfo.WithVersion(cliv2.GetFullVersion()))
 
-	rootCommand := prepareRootCommand()
+	helpRouter := &helprouting.Router{
+		LegacyHelp:   runLegacyHelp,
+		OnHelpCalled: func() { helpProvided = true },
+	}
+	rootCommand := prepareRootCommand(helpRouter)
 	// omit the first arg which is always `snyk`
 	_ = rootCommand.ParseFlags(os.Args[1:])
 
@@ -556,7 +560,7 @@ func mainWithErrorCode(additionalExts []workflow.ExtensionInit) int {
 	)
 	err = globalConfiguration.AddFlagSet(rootCommand.LocalFlags())
 	if err != nil {
-		fmt.Fprintln(os.Stderr, "Failed to add flags to root command", err)
+		_, _ = fmt.Fprintln(os.Stderr, "Failed to add flags to root command", err)
 	}
 
 	// ensure to init configuration before using it
@@ -670,7 +674,7 @@ func mainWithErrorCode(additionalExts []workflow.ExtensionInit) int {
 		globalLogger.Printf("Using Legacy CLI to serve the command. (reason: %v)", err)
 		err = defaultCmd(os.Args[1:])
 	case handleErrorShowHelp:
-		err = help(nil, []string{})
+		err = helpRouter.Help(nil, rootCommand, os.Args[1:])
 	case handleErrorUnhandled:
 		// ignore
 	}

cliv2/pkg/core/main_test.go

@@ -32,6 +32,7 @@ import (
 	"github.com/snyk/cli/cliv2/internal/cliv2"
 	"github.com/snyk/cli/cliv2/internal/constants"
 	clierrors "github.com/snyk/cli/cliv2/internal/errors"
+	"github.com/snyk/cli/cliv2/pkg/helprouting"
 )
 
 func cleanup() {
@@ -144,7 +145,7 @@ func Test_CreateCommandsForWorkflowWithSubcommands(t *testing.T) {
 	}
 
 	_ = globalEngine.Init()
-	rootCommand := prepareRootCommand()
+	rootCommand := prepareRootCommand(testHelpRouter())
 
 	// invoke method under test
 	createCommandsForWorkflows(rootCommand, globalEngine)
@@ -763,3 +764,9 @@ func loadJsonFile(t *testing.T, filename string) []byte {
 	assert.NoError(t, err)
 	return byteValue
 }
+
+func testHelpRouter() *helprouting.Router {
+	return &helprouting.Router{
+		LegacyHelp: func() error { return nil },
+	}
+}

cliv2/pkg/helpdocs/helpdocs.go

@@ -0,0 +1,71 @@
+package helpdocs
+
+import (
+	_ "embed"
+	"regexp"
+	"strings"
+)
+
+//go:embed manifest.txt
+var manifest string
+
+var docFiles map[string]struct{}
+
+var nonDocChars = regexp.MustCompile(`[^a-zA-Z0-9-]`)
+
+func init() {
+	docFiles = manifestFileSet(manifest)
+}
+
+// manifestFileSet builds the doc filename set from manifest text.
+// Trims trailing carriage returns so CRLF-checked-out manifests still match lookups.
+func manifestFileSet(manifestText string) map[string]struct{} {
+	files := make(map[string]struct{})
+	for _, line := range manifestLines(manifestText) {
+		files[line] = struct{}{}
+	}
+	return files
+}
+
+func manifestLines(manifestText string) []string {
+	var lines []string
+	for _, line := range strings.Split(strings.TrimSpace(manifestText), "\n") {
+		line = strings.TrimSuffix(line, "\r")
+		if line != "" {
+			lines = append(lines, line)
+		}
+	}
+	return lines
+}
+
+// helpFileName mirrors src/cli/commands/help/index.ts join + cleanse.
+func helpFileName(segments []string) string {
+	joined := strings.Join(segments, "-")
+	cleaned := nonDocChars.ReplaceAllString(joined, "")
+	return cleaned + ".md"
+}
+
+// HasUserDoc reports whether legacy user-doc help should be shown for command segments.
+// Empty segments → true (top-level README via legacy help).
+// Non-empty segments → true only if a matching .md exists during walk-back (README excluded).
+func HasUserDoc(segments []string) bool {
+	return hasUserDoc(docFiles, segments)
+}
+
+func hasUserDoc(files map[string]struct{}, segments []string) bool {
+	if len(segments) == 0 {
+		return true
+	}
+	if len(files) == 0 {
+		// Missing or empty manifest at build time: prefer legacy help lookup.
+		return true
+	}
+	args := append([]string(nil), segments...)
+	for len(args) > 0 {
+		if _, ok := files[helpFileName(args)]; ok {
+			return true
+		}
+		args = args[:len(args)-1]
+	}
+	return false
+}

cliv2/pkg/helpdocs/helpdocs_test.go

@@ -0,0 +1,96 @@
+package helpdocs
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func testDocFiles() map[string]struct{} {
+	names := []string{
+		"README.md",
+		"test.md",
+		"container.md",
+		"container-test.md",
+		"iac-describe.md",
+		"redteam.md",
+	}
+	files := make(map[string]struct{}, len(names))
+	for _, name := range names {
+		files[name] = struct{}{}
+	}
+	return files
+}
+
+func Test_helpFileName(t *testing.T) {
+	assert.Equal(t, "container-test.md", helpFileName([]string{"container", "test"}))
+	assert.Equal(t, "iac-describe.md", helpFileName([]string{"iac", "describe"}))
+	assert.Equal(t, "secrets-test.md", helpFileName([]string{"secrets", "test"}))
+}
+
+func Test_hasUserDoc(t *testing.T) {
+	files := testDocFiles()
+
+	tests := map[string]struct {
+		segments []string
+		want     bool
+	}{
+		"empty uses readme path":             {segments: []string{}, want: true},
+		"test command":                       {segments: []string{"test"}, want: true},
+		"container test subcommand":          {segments: []string{"container", "test"}, want: true},
+		"iac describe subcommand":            {segments: []string{"iac", "describe"}, want: true},
+		"unknown command":                    {segments: []string{"rainmaker"}, want: false},
+		"undocumented secrets test":          {segments: []string{"secrets", "test"}, want: false},
+		"redteam setup walks back to parent": {segments: []string{"redteam", "setup"}, want: true},
+		"undocumented agent-scan":            {segments: []string{"agent-scan"}, want: false},
+	}
+
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			assert.Equal(t, tc.want, hasUserDoc(files, tc.segments))
+		})
+	}
+}
+
+func Test_HasUserDoc_usesEmbeddedManifest(t *testing.T) {
+	assert.True(t, HasUserDoc([]string{"test"}))
+	assert.NotEmpty(t, docFiles)
+}
+
+func Test_manifestFileSet_stripsCRLFLineEndings(t *testing.T) {
+	files := manifestFileSet("test.md\r\ncontainer-test.md\r\n")
+
+	assert.True(t, hasUserDoc(files, []string{"test"}))
+	assert.True(t, hasUserDoc(files, []string{"container", "test"}))
+	assert.False(t, hasUserDoc(files, []string{"rainmaker"}))
+}
+
+func Test_manifestMatchesHelpCLICommands(t *testing.T) {
+	helpDir := filepath.Join("..", "..", "..", "help", "cli-commands")
+	entries, err := os.ReadDir(helpDir)
+	require.NoError(t, err, "help/cli-commands must exist; run from repo root via go test ./pkg/helpdocs")
+
+	var fromDisk []string
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".md") {
+			continue
+		}
+		fromDisk = append(fromDisk, entry.Name())
+	}
+	sort.Strings(fromDisk)
+
+	fromManifest := manifestEntries()
+	assert.Equal(t, fromDisk, fromManifest,
+		"embedded manifest.txt is out of sync with help/cli-commands; run: make -C cliv2 helpdocs-manifest")
+}
+
+func manifestEntries() []string {
+	entries := manifestLines(manifest)
+	sort.Strings(entries)
+	return entries
+}