feat(plugins): add auth0 plugin commands

internal/cli/auth_env.go

@@ -106,6 +106,19 @@ func validateAuthMode(getenv func(string) string) error {
 	}
 }
 
+// envTenantConflictError is the error for a --tenant that names another tenant
+// than the AUTH0_DOMAIN that fixes it in env auth mode.
+func envTenantConflictError(tenant, domain string) error {
+	return authError{
+		err: fmt.Errorf(
+			"--tenant %q conflicts with %s=%q; in %s=%s mode the tenant is fixed by %s. "+
+				"Drop --tenant, or set %s to the tenant you want to target",
+			tenant, envDomain, domain, authModeEnvVar, authModeEnv, envDomain, envDomain,
+		),
+		reason: "env_auth_tenant_conflict",
+	}
+}
+
 // setupWithEnvAuthentication authenticates purely from environment variables,
 // touching neither the on-disk config nor the keychain. It accepts a pre-minted
 // Management API token via AUTH0_API_TOKEN, or client credentials via
@@ -136,14 +149,7 @@ func (c *cli) setupWithEnvAuthentication(ctx context.Context) error {
 	// tenant.
 	if c.tenantExplicit {
 		if requested := strings.TrimSpace(c.tenant); !strings.EqualFold(requested, domain) {
-			return authError{
-				err: fmt.Errorf(
-					"--tenant %q conflicts with %s=%q; in %s=%s mode the tenant is fixed by %s. "+
-						"Drop --tenant, or set %s to the tenant you want to target",
-					c.tenant, envDomain, domain, authModeEnvVar, authModeEnv, envDomain, envDomain,
-				),
-				reason: "env_auth_tenant_conflict",
-			}
+			return envTenantConflictError(c.tenant, domain)
 		}
 	}
 

internal/cli/cli.go

@@ -44,6 +44,10 @@ type cli struct {
 	renderer *display.Renderer
 	tracker  *analytics.Tracker
 
+	// Builds the plugin service when a plugin command first needs it. When it
+	// is nil the real one is built. Tests set it to inject a fake.
+	plugins func() (*pluginService, error)
+
 	// Set of flags which are user specified.
 	debug               bool
 	tenant              string

internal/cli/doc-gen.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"text/template"
 
@@ -15,6 +16,11 @@ import (
 const (
 	docsPath = "./docs/"
 
+	// The annotation with this key, set to "true" on a command, keeps the command
+	// and everything below it out of the generated docs and out of the links to
+	// them.
+	skipDocsAnnotation = "skipDocs"
+
 	associatedCommandsFragment = `{{range .AssociatedCommands}}- [{{.CommandPath}}]({{ link .CommandPath }}) - {{.Short}}
 {{end}}`
 
@@ -169,6 +175,11 @@ type page struct {
 // GenerateDocs will generate the documentation
 // for all the commands under the ./docs folder.
 func GenerateDocs() error {
+	return GenMarkdownTree(newDocsRoot(), docsPath)
+}
+
+// newDocsRoot returns the command tree that the docs are generated from.
+func newDocsRoot() *cobra.Command {
 	baseCmd := &cobra.Command{
 		Use:   "auth0",
 		Short: rootShort,
@@ -179,12 +190,20 @@ func GenerateDocs() error {
 	addPersistentFlags(baseCmd, cli)
 	addSubCommands(baseCmd, cli)
 
-	return GenMarkdownTree(baseCmd, docsPath)
+	return baseCmd
+}
+
+// documentedCommands returns the commands that have a page in the docs, which is
+// all of them except those that are marked with skipDocsAnnotation.
+func documentedCommands(commands []*cobra.Command) []*cobra.Command {
+	return slices.DeleteFunc(slices.Clone(commands), func(c *cobra.Command) bool {
+		return c.Annotations[skipDocsAnnotation] == "true"
+	})
 }
 
 // GenMarkdownTree is the same as GenMarkdownTree, but with linkHandler.
 func GenMarkdownTree(cmd *cobra.Command, dir string) error {
-	for _, c := range cmd.Commands() {
+	for _, c := range documentedCommands(cmd.Commands()) {
 		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
@@ -222,7 +241,7 @@ func GenerateHomepage(cmd *cobra.Command, w io.Writer) error {
 
 	pageData := page{
 		CommandPath:        cmd.CommandPath(),
-		AssociatedCommands: cmd.Commands(),
+		AssociatedCommands: documentedCommands(cmd.Commands()),
 	}
 
 	return GeneratePage(w, "homepageTemplate", templateBody, pageData)
@@ -233,7 +252,7 @@ func GenerateParentPage(cmd *cobra.Command, w io.Writer) error {
 	templateBody := fmt.Sprintf(parentPageTemplate, associatedCommandsFragment)
 
 	hasRunnableChildren := false
-	for _, c := range cmd.Commands() {
+	for _, c := range documentedCommands(cmd.Commands()) {
 		if c.Runnable() {
 			hasRunnableChildren = true
 		}
@@ -248,7 +267,7 @@ func GenerateParentPage(cmd *cobra.Command, w io.Writer) error {
 		Name:                cmd.CommandPath(),
 		Description:         cmd.Long,
 		CommandPath:         cmd.CommandPath(),
-		AssociatedCommands:  cmd.Commands(),
+		AssociatedCommands:  documentedCommands(cmd.Commands()),
 		ParentCommandPath:   parentCommand,
 		HasRunnableChildren: hasRunnableChildren,
 	}
@@ -262,7 +281,7 @@ func GenerateCommandPage(cmd *cobra.Command, w io.Writer) error {
 
 	parentCommand := cmd.Parent()
 
-	associatedCommands := parentCommand.Commands()
+	associatedCommands := documentedCommands(parentCommand.Commands())
 	if parentCommand.Name() == "auth0" {
 		associatedCommands = nil
 	}

internal/cli/doc-gen_test.go

@@ -0,0 +1,97 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// readDocs generates the docs of the tree into a new directory and returns the
+// content of every page by file name.
+func readDocs(t *testing.T, root *cobra.Command) map[string]string {
+	t.Helper()
+
+	dir := t.TempDir()
+	require.NoError(t, GenMarkdownTree(root, dir))
+
+	entries, err := os.ReadDir(dir)
+	require.NoError(t, err)
+
+	pages := make(map[string]string, len(entries))
+
+	for _, entry := range entries {
+		content, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+		require.NoError(t, err)
+
+		pages[entry.Name()] = string(content)
+	}
+
+	return pages
+}
+
+func TestGenMarkdownTree_LeavesOutThePluginCommands(t *testing.T) {
+	root := newDocsRoot()
+
+	group, _, err := root.Find([]string{"plugin"})
+	require.NoError(t, err)
+	require.NotSame(t, root, group, "the plugin group must be in the tree, or this test proves nothing")
+
+	pages := readDocs(t, root)
+
+	assert.Contains(t, pages, "auth0.md")
+	assert.Contains(t, pages, "auth0_apps.md")
+
+	for name, content := range pages {
+		assert.False(t, strings.HasPrefix(name, "auth0_plugin"), "page %s", name)
+		assert.NotContains(t, content, "auth0_plugin", "link in %s", name)
+		assert.NotContains(t, content, "auth0 plugin", "mention in %s", name)
+	}
+}
+
+func TestGenMarkdownTree_SkipsAnnotatedCommands(t *testing.T) {
+	newTree := func() *cobra.Command {
+		run := func(*cobra.Command, []string) {}
+		skip := map[string]string{skipDocsAnnotation: "true"}
+
+		root := &cobra.Command{Use: "auth0"}
+
+		things := &cobra.Command{Use: "things", Long: "Things."}
+		things.AddCommand(
+			&cobra.Command{Use: "keep", Short: "Keep it", Run: run},
+			&cobra.Command{Use: "hide", Short: "Hide it", Run: run, Annotations: skip},
+		)
+
+		onlyHidden := &cobra.Command{Use: "only-hidden", Long: "Only hidden."}
+		onlyHidden.AddCommand(&cobra.Command{Use: "hide", Short: "Hide it", Run: run, Annotations: skip})
+
+		hidden := &cobra.Command{Use: "secret", Short: "Secret group", Annotations: skip}
+		hidden.AddCommand(&cobra.Command{Use: "child", Short: "Child", Run: run})
+
+		root.AddCommand(things, onlyHidden, hidden)
+
+		return root
+	}
+
+	pages := readDocs(t, newTree())
+
+	assert.Contains(t, pages, "auth0_things_keep.md")
+	assert.NotContains(t, pages, "auth0_things_hide.md")
+	assert.NotContains(t, pages, "auth0_only-hidden_hide.md")
+	assert.NotContains(t, pages, "auth0_secret.md")
+	assert.NotContains(t, pages, "auth0_secret_child.md")
+
+	assert.NotContains(t, pages["auth0.md"], "auth0_secret")
+	assert.Contains(t, pages["auth0.md"], "auth0_things.md")
+
+	assert.Contains(t, pages["auth0_things.md"], "auth0_things_keep.md")
+	assert.NotContains(t, pages["auth0_things.md"], "auth0_things_hide")
+	assert.NotContains(t, pages["auth0_things_keep.md"], "auth0_things_hide")
+
+	assert.NotContains(t, pages["auth0_only-hidden.md"], "has_children")
+	assert.NotContains(t, pages["auth0_only-hidden.md"], "auth0_only-hidden_hide")
+}