feat: add list command with global filters

cmd/list.go

@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/rogeecn/renamer/internal/listing"
+	"github.com/rogeecn/renamer/internal/output"
+)
+
+func newListCommand() *cobra.Command {
+	var (
+		format   string
+		maxDepth int
+	)
+
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "Display rename candidates matched by the active filters",
+		Long:  "Enumerate files and directories using the same filters that the rename command will honor.",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			req, err := listing.ScopeFromCmd(cmd)
+			if err != nil {
+				return err
+			}
+
+			req.Format = format
+			req.MaxDepth = maxDepth
+
+			formatter, err := output.NewFormatter(req.Format)
+			if err != nil {
+				return err
+			}
+
+			service := listing.NewService()
+			summary, err := service.List(cmd.Context(), req, formatter, cmd.OutOrStdout())
+			if err != nil {
+				return err
+			}
+
+			if summary.Total() == 0 {
+				_, err = fmt.Fprintln(cmd.OutOrStdout(), listing.EmptyResultMessage(req))
+				return err
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVar(&format, "format", listing.FormatTable, "Output format: table or plain")
+	cmd.Flags().IntVar(&maxDepth, "max-depth", 0, "Maximum recursion depth (0 = unlimited)")
+
+	return cmd
+}
+
+func init() {
+	rootCmd.AddCommand(newListCommand())
+}

cmd/root.go

@@ -1,6 +1,5 @@
 /*
 Copyright © 2025 NAME HERE <EMAIL ADDRESS>
-
 */
 package cmd
 
@@ -8,23 +7,16 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
+
+	"github.com/rogeecn/renamer/internal/listing"
 )
 
-
-
-// rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
 	Use:   "renamer",
-	Short: "A brief description of your application",
-	Long: `A longer description that spans multiple lines and likely contains
-examples and usage of using your application. For example:
-
-Cobra is a CLI library for Go that empowers applications.
-This application is a tool to generate the needed files
-to quickly create a Cobra application.`,
-	// Uncomment the following line if your bare application
-	// has an action associated with it:
-	// Run: func(cmd *cobra.Command, args []string) { },
+	Short: "Safe, scriptable batch renaming utility",
+	Long: `Renamer provides preview-first, undoable rename operations for files and directories.
+Use subcommands like "preview", "rename", and "list" with shared scope flags to target exactly
+the paths you intend to change.`,
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.
@@ -37,15 +29,5 @@ func Execute() {
 }
 
 func init() {
-	// Here you will define your flags and configuration settings.
-	// Cobra supports persistent flags, which, if defined here,
-	// will be global for your application.
-
-	// rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.renamer.yaml)")
-
-	// Cobra also supports local flags, which will only run
-	// when this action is called directly.
-	rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+	listing.RegisterScopeFlags(rootCmd.PersistentFlags())
 }
-
-