introduce debug commands (#4533)

adds the primary `debug` command to the cli as
a hidden command option.  Also includes the scaffold for
a `metadata-files` command that could be used to print
out the metadata files in the backup.

---

#### Does this PR need a docs update or release note?

- [x] ⛔ No

#### Type of change

- [x] 🌻 Feature

#### Test Plan

- [x] ⚡ Unit test

src/cli/debug/debug.go

@@ -0,0 +1,105 @@
+package debug
+
+import (
+	"context"
+
+	"github.com/spf13/cobra"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	. "github.com/alcionai/corso/src/cli/print"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+var subCommandFuncs = []func() *cobra.Command{
+	metadataFilesCmd,
+}
+
+var debugCommands = []func(cmd *cobra.Command) *cobra.Command{
+	addOneDriveCommands,
+	addSharePointCommands,
+	addGroupsCommands,
+	addExchangeCommands,
+}
+
+// AddCommands attaches all `corso debug * *` commands to the parent.
+func AddCommands(cmd *cobra.Command) {
+	debugC, _ := utils.AddCommand(cmd, debugCmd(), utils.MarkDebugCommand())
+
+	for _, sc := range subCommandFuncs {
+		subCommand := sc()
+		utils.AddCommand(debugC, subCommand, utils.MarkDebugCommand())
+
+		for _, addTo := range debugCommands {
+			addTo(subCommand)
+			flags.AddAllProviderFlags(subCommand)
+			flags.AddAllStorageFlags(subCommand)
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+const debugCommand = "debug"
+
+// The debug category of commands.
+// `corso debug [<subcommand>] [<flag>...]`
+func debugCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   debugCommand,
+		Short: "debugging & troubleshooting utilities",
+		Long:  `debug the data stored in corso.`,
+		RunE:  handledebugCmd,
+		Args:  cobra.NoArgs,
+	}
+}
+
+// Handler for flat calls to `corso debug`.
+// Produces the same output as `corso debug --help`.
+func handledebugCmd(cmd *cobra.Command, args []string) error {
+	return cmd.Help()
+}
+
+// The debug metadataFiles subcommand.
+// `corso debug metadata-files <service> [<flag>...]`
+var metadataFilesCommand = "metadata-files"
+
+func metadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   metadataFilesCommand,
+		Short: "display all the metadata file contents stored by the service",
+		RunE:  handleMetadataFilesCmd,
+		Args:  cobra.NoArgs,
+	}
+}
+
+// Handler for calls to `corso debug metadata-files`.
+// Produces the same output as `corso debug metadata-files --help`.
+func handleMetadataFilesCmd(cmd *cobra.Command, args []string) error {
+	return cmd.Help()
+}
+
+// ---------------------------------------------------------------------------
+// runners
+// ---------------------------------------------------------------------------
+
+func runMetadataFiles(
+	ctx context.Context,
+	cmd *cobra.Command,
+	args []string,
+	sel selectors.Selector,
+	debugID, serviceName string,
+) error {
+	r, _, err := utils.GetAccountAndConnect(ctx, cmd, sel.PathService())
+	if err != nil {
+		return Only(ctx, err)
+	}
+
+	defer utils.CloseRepo(ctx, r)
+
+	// TODO: read and print out all metadata files in the debug
+
+	return nil
+}

src/cli/debug/exchange.go

@@ -0,0 +1,71 @@
+package debug
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+// called by debug.go to map subcommands to provider-specific handling.
+func addExchangeCommands(cmd *cobra.Command) *cobra.Command {
+	var (
+		c  *cobra.Command
+		fs *pflag.FlagSet
+	)
+
+	switch cmd.Use {
+	case metadataFilesCommand:
+		c, fs = utils.AddCommand(cmd, exchangeMetadataFilesCmd(), utils.MarkDebugCommand())
+
+		c.Use = c.Use + " " + exchangeServiceCommandUseSuffix
+
+		// Flags addition ordering should follow the order we want them to appear in help and docs:
+		// More generic (ex: --user) and more frequently used flags take precedence.
+		fs.SortFlags = false
+
+		flags.AddBackupIDFlag(c, true)
+	}
+
+	return c
+}
+
+const (
+	exchangeServiceCommand          = "exchange"
+	exchangeServiceCommandUseSuffix = "--backup <backupId>"
+
+	//nolint:lll
+	exchangeServiceCommandDebugExamples = `# Display file contents for backup 1234abcd
+corso debug metadata-files exchange --backup 1234abcd-12ab-cd34-56de-1234abcd`
+)
+
+// `corso debug metadata-files exchange [<flag>...] <destination>`
+func exchangeMetadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     exchangeServiceCommand,
+		Short:   "Display exchange metadata file content",
+		RunE:    metadataFilesExchangeCmd,
+		Args:    cobra.NoArgs,
+		Example: exchangeServiceCommandDebugExamples,
+	}
+}
+
+func metadataFilesExchangeCmd(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	if utils.HasNoFlagsAndShownHelp(cmd) {
+		return nil
+	}
+
+	// opts := utils.MakeExchangeOpts(cmd)
+
+	if flags.RunModeFV == flags.RunModeFlagTest {
+		return nil
+	}
+
+	sel := selectors.NewExchangeBackup([]string{"unused-placeholder"})
+
+	return runMetadataFiles(ctx, cmd, args, sel.Selector, flags.BackupIDFV, "Exchange")
+}

src/cli/debug/exchange_test.go

@@ -0,0 +1,77 @@
+package debug
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/suite"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	flagsTD "github.com/alcionai/corso/src/cli/flags/testdata"
+	cliTD "github.com/alcionai/corso/src/cli/testdata"
+	"github.com/alcionai/corso/src/internal/tester"
+)
+
+type ExchangeUnitSuite struct {
+	tester.Suite
+}
+
+func TestExchangeUnitSuite(t *testing.T) {
+	suite.Run(t, &ExchangeUnitSuite{Suite: tester.NewUnitSuite(t)})
+}
+
+func (suite *ExchangeUnitSuite) TestExchangeCommands() {
+	expectUse := exchangeServiceCommand + " " + exchangeServiceCommandUseSuffix
+
+	table := []struct {
+		name        string
+		use         string
+		expectUse   string
+		expectShort string
+		expectRunE  func(*cobra.Command, []string) error
+	}{
+		{
+			name:        "metdata-files exchange",
+			use:         metadataFilesCommand,
+			expectUse:   expectUse,
+			expectShort: exchangeMetadataFilesCmd().Short,
+			expectRunE:  metadataFilesExchangeCmd,
+		},
+	}
+	for _, test := range table {
+		suite.Run(test.name, func() {
+			t := suite.T()
+			parent := &cobra.Command{Use: metadataFilesCommand}
+
+			cmd := cliTD.SetUpCmdHasFlags(
+				t,
+				parent,
+				addExchangeCommands,
+				[]cliTD.UseCobraCommandFn{
+					flags.AddAllProviderFlags,
+					flags.AddAllStorageFlags,
+				},
+				flagsTD.WithFlags(
+					exchangeServiceCommand,
+					[]string{
+						"--" + flags.RunModeFN, flags.RunModeFlagTest,
+						"--" + flags.BackupFN, flagsTD.BackupInput,
+					},
+					flagsTD.PreparedProviderFlags(),
+					flagsTD.PreparedStorageFlags()))
+
+			cliTD.CheckCmdChild(
+				t,
+				parent,
+				3,
+				test.expectUse,
+				test.expectShort,
+				test.expectRunE)
+
+			assert.Equal(t, flagsTD.BackupInput, flags.BackupIDFV)
+			flagsTD.AssertProviderFlags(t, cmd)
+			flagsTD.AssertStorageFlags(t, cmd)
+		})
+	}
+}

src/cli/debug/groups.go

@@ -0,0 +1,72 @@
+package debug
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+// called by debug.go to map subcommands to provider-specific handling.
+func addGroupsCommands(cmd *cobra.Command) *cobra.Command {
+	var (
+		c  *cobra.Command
+		fs *pflag.FlagSet
+	)
+
+	switch cmd.Use {
+	case metadataFilesCommand:
+		c, fs = utils.AddCommand(cmd, groupsMetadataFilesCmd(), utils.MarkDebugCommand())
+
+		c.Use = c.Use + " " + groupsServiceCommandUseSuffix
+
+		// Flags addition ordering should follow the order we want them to appear in help and docs:
+		// More generic (ex: --user) and more frequently used flags take precedence.
+		fs.SortFlags = false
+
+		flags.AddBackupIDFlag(c, true)
+	}
+
+	return c
+}
+
+// TODO: correct examples
+const (
+	groupsServiceCommand          = "groups"
+	groupsServiceCommandUseSuffix = "--backup <backupId>"
+
+	//nolint:lll
+	groupsServiceCommandDebugExamples = `# Display file contents for backup 1234abcd
+	corso debug metadata-files groups --backup 1234abcd-12ab-cd34-56de-1234abcd`
+)
+
+// `corso debug metadata-files groups [<flag>...] <destination>`
+func groupsMetadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     groupsServiceCommand,
+		Short:   "Display groups metadata file content",
+		RunE:    metadataFilesGroupsCmd,
+		Args:    cobra.NoArgs,
+		Example: groupsServiceCommandDebugExamples,
+	}
+}
+
+func metadataFilesGroupsCmd(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	if utils.HasNoFlagsAndShownHelp(cmd) {
+		return nil
+	}
+
+	// opts := utils.MakeGroupsOpts(cmd)
+
+	if flags.RunModeFV == flags.RunModeFlagTest {
+		return nil
+	}
+
+	sel := selectors.NewGroupsBackup([]string{"unused-placeholder"})
+
+	return runMetadataFiles(ctx, cmd, args, sel.Selector, flags.BackupIDFV, "Groups")
+}