Merge pull request #605 from DefangLabs/lio-more-help

add more help info to the CLI

Author: lionello

src/cmd/cli/command/commands.go

@@ -173,6 +173,7 @@ func SetupCommands(version string) {
 
 	// Generate Command
 	RootCmd.AddCommand(generateCmd)
+	RootCmd.AddCommand(newCmd)
 
 	// Get Services Command
 	getServicesCmd.Flags().BoolP("long", "l", false, "show more details")
@@ -214,9 +215,17 @@ func SetupCommands(version string) {
 	composeCmd.AddCommand(composeDownCmd)
 	composeStartCmd.Flags().Bool("force", false, "force a build of the image even if nothing has changed")
 	composeCmd.AddCommand(composeStartCmd)
-	RootCmd.AddCommand(composeCmd)
 	composeCmd.AddCommand(composeRestartCmd)
 	composeCmd.AddCommand(composeStopCmd)
+	composeCmd.AddCommand(getServicesCmd) // like docker compose ls
+	RootCmd.AddCommand(composeCmd)
+
+	// Add up/down commands to the root as well
+	RootCmd.AddCommand(composeDownCmd)
+	RootCmd.AddCommand(composeUpCmd)
+	// RootCmd.AddCommand(composeStartCmd)
+	// RootCmd.AddCommand(composeRestartCmd)
+	// RootCmd.AddCommand(composeStopCmd)
 
 	// Debug Command
 	debugCmd.Flags().String("etag", "", "deployment ID (ETag) of the service")
@@ -270,7 +279,7 @@ var RootCmd = &cobra.Command{
 	SilenceErrors: true,
 	Use:           "defang",
 	Args:          cobra.NoArgs,
-	Short:         "Defang CLI manages services on the Defang cluster",
+	Short:         "Defang CLI is used to develop, deploy, and debug your cloud services",
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) (err error) {
 
 		term.SetDebug(doDebug)
@@ -430,10 +439,10 @@ var certGenerateCmd = &cobra.Command{
 }
 
 var generateCmd = &cobra.Command{
-	Use:     "generate [SAMPLE]",
+	Use:     "generate",
 	Args:    cobra.MaximumNArgs(1),
-	Aliases: []string{"gen", "new", "init"},
-	Short:   "Generate a sample Defang project in the current folder",
+	Aliases: []string{"gen"},
+	Short:   "Generate a sample Defang project",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var sample, language, defaultFolder string
 		if len(args) > 0 {
@@ -446,12 +455,12 @@ var generateCmd = &cobra.Command{
 			}
 			return cli.InitFromSamples(cmd.Context(), "", []string{sample})
 		}
+
 		sampleList, fetchSamplesErr := cli.FetchSamples(cmd.Context())
 		if sample == "" {
 			if err := survey.AskOne(&survey.Select{
 				Message: "Choose the language you'd like to use:",
-				Options: []string{"Nodejs", "Golang", "Python"},
-				Default: "Nodejs",
+				Options: cli.SupportedLanguages,
 				Help:    "The project code will be in the language you choose here.",
 			}, &language); err != nil {
 				return err
@@ -604,6 +613,14 @@ var generateCmd = &cobra.Command{
 	},
 }
 
+var newCmd = &cobra.Command{
+	Use:     "new [SAMPLE]",
+	Args:    cobra.MaximumNArgs(1),
+	Aliases: []string{"init"},
+	Short:   "Create a new Defang project from a sample",
+	RunE:    generateCmd.RunE,
+}
+
 func collectUnsetEnvVars(project *proj.Project) []string {
 	var envVars []string
 	if project != nil {
@@ -669,6 +686,7 @@ var getVersionCmd = &cobra.Command{
 var tailCmd = &cobra.Command{
 	Use:         "tail",
 	Annotations: authNeededAnnotation,
+	Aliases:     []string{"logs"},
 	Args:        cobra.NoArgs,
 	Short:       "Tail logs from one or more services",
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -775,7 +793,7 @@ var configSetCmd = &cobra.Command{
 		}
 		term.Info("Updated value for", name)
 
-		printDefangHint("To update the deployed values, do:", "compose start")
+		printDefangHint("To update the deployed values, do:", "compose restart")
 		return nil
 	},
 }
@@ -818,20 +836,33 @@ var composeCmd = &cobra.Command{
 	Aliases: []string{"stack"},
 	Args:    cobra.NoArgs,
 	Short:   "Work with local Compose files",
+	Long: `Define and deploy multi-container applications with Defang. Most compose commands require
+a "compose.yaml" file. The simplest "compose.yaml" file with a single service is:
+
+services:
+  app:              # the name of the service
+    build: .        # the folder with the Dockerfile and app sources (. means current folder)
+    ports:
+      - 80          # the port the service listens on for HTTP requests
+`,
 }
 
 var composeUpCmd = &cobra.Command{
 	Use:         "up",
 	Annotations: authNeededAnnotation,
 	Args:        cobra.NoArgs, // TODO: takes optional list of service names
-	Short:       "Like 'start' but immediately tracks the progress of the deployment",
+	Short:       "Reads a Compose file and deploy a new project or update an existing project",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var force, _ = cmd.Flags().GetBool("force")
 		var detach, _ = cmd.Flags().GetBool("detach")
 
 		since := time.Now()
 		deploy, project, err := cli.ComposeUp(cmd.Context(), client, force)
 		if err != nil {
+			if !errors.Is(err, types.ErrComposeFileNotFound) {
+				return err
+			}
+			printDefangHint("To start a new project, do:", "new")
 			return err
 		}
 
@@ -1019,7 +1050,7 @@ var composeDownCmd = &cobra.Command{
 	Aliases:     []string{"rm"},
 	Annotations: authNeededAnnotation,
 	Args:        cobra.NoArgs, // TODO: takes optional list of service names
-	Short:       "Like 'stop' but also deprovisions the services from the cluster",
+	Short:       "Reads a Compose file and deprovisions its services",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var detach, _ = cmd.Flags().GetBool("detach")
 

src/pkg/cli/compose/validation.go

@@ -13,6 +13,8 @@ import (
 	compose "github.com/compose-spec/compose-go/v2/types"
 )
 
+var ErrDockerfileNotFound = errors.New("dockerfile not found")
+
 func ValidateProject(project *compose.Project) error {
 	if project == nil {
 		return errors.New("no project found")
@@ -111,7 +113,7 @@ func ValidateProject(project *compose.Project) error {
 				// Check if the dockerfile exists
 				dockerfilePath := filepath.Join(svccfg.Build.Context, svccfg.Build.Dockerfile)
 				if _, err := os.Stat(dockerfilePath); err != nil {
-					return fmt.Errorf("service %q: dockerfile not found: %q", svccfg.Name, dockerfilePath)
+					return fmt.Errorf("service %q: %w: %q", svccfg.Name, ErrDockerfileNotFound, dockerfilePath)
 				}
 			}
 			if svccfg.Build.SSH != nil {

src/pkg/cli/debug.go

@@ -120,6 +120,24 @@ func findMatchingProjectFiles(project *types.Project, services []string) []*defa
 	return files
 }
 
+func IsProjectFile(basename string) bool {
+	return filepathMatchAny(patterns, basename)
+}
+
+func filepathMatchAny(patterns []string, name string) bool {
+	for _, pattern := range patterns {
+		matched, err := filepath.Match(pattern, name)
+		if err != nil {
+			term.Debug("error matching pattern:", err)
+			continue
+		}
+		if matched {
+			return true // file matched, no need to check other patterns
+		}
+	}
+	return false
+}
+
 func findMatchingFiles(folder, dockerfile string) []*defangv1.File {
 	var files []*defangv1.File
 
@@ -137,17 +155,9 @@ func findMatchingFiles(folder, dockerfile string) []*defangv1.File {
 			return errFileLimitReached
 		}
 
-		for _, pattern := range patterns {
-			matched, err := filepath.Match(pattern, info.Name())
-			if err != nil {
-				term.Debug("error matching pattern:", err)
-				continue
-			}
-			if matched {
-				if file := readFile(path); file != nil {
-					files = append(files, file)
-					break // file matched, no need to check other patterns
-				}
+		if IsProjectFile(info.Name()) {
+			if file := readFile(path); file != nil {
+				files = append(files, file)
 			}
 		}
 		return nil

src/pkg/cli/generate.go

@@ -11,6 +11,8 @@ import (
 	defangv1 "github.com/DefangLabs/defang/src/protos/io/defang/v1"
 )
 
+var SupportedLanguages = []string{"Nodejs", "Golang", "Python"}
+
 func GenerateWithAI(ctx context.Context, client client.Client, language, dir, description string) ([]string, error) {
 	if DoDryRun {
 		term.Warn("Dry run, not generating files")

src/pkg/cli/new.go

@@ -50,7 +50,17 @@ func FetchSamples(ctx context.Context) ([]Sample, error) {
 	return samples, err
 }
 
+// MixinFromSamples copies the sample files into the given directory, skipping existing files.
+func MixinFromSample(ctx context.Context, dir string, name string) error {
+	return copyFromSamples(ctx, dir, []string{name}, true)
+}
+
+// InitFromSamples copies the sample(s) into the given directory, aborting if any files already exist.
 func InitFromSamples(ctx context.Context, dir string, names []string) error {
+	return copyFromSamples(ctx, dir, names, false)
+}
+
+func copyFromSamples(ctx context.Context, dir string, names []string, skipExisting bool) error {
 	const repo = "samples"
 	const branch = "main"
 
@@ -99,8 +109,12 @@ func InitFromSamples(ctx context.Context, dir string, names []string) error {
 					}
 					continue
 				}
-				if err := createFile(path, h, tarReader); err != nil {
-					return err
+				// Use the same mode as the original file (so scripts are executable, etc.)
+				if err := writeFileExcl(path, tarReader, h.FileInfo().Mode()); err != nil {
+					if !skipExisting || !os.IsExist(err) {
+						return err
+					}
+					term.Warnf("File %q already exists, skipping", path)
 				}
 			}
 		}
@@ -111,14 +125,14 @@ func InitFromSamples(ctx context.Context, dir string, names []string) error {
 	return nil
 }
 
-func createFile(base string, h *tar.Header, tarReader *tar.Reader) error {
-	// Like os.Create, but with the same mode as the original file (so scripts are executable, etc.)
-	file, err := os.OpenFile(base, os.O_RDWR|os.O_CREATE|os.O_EXCL, h.FileInfo().Mode())
+// writeFileExcl is like os.WriteFile, but with O_EXCL to avoid overwriting existing files.
+func writeFileExcl(base string, reader io.Reader, mode os.FileMode) error {
+	file, err := os.OpenFile(base, os.O_RDWR|os.O_CREATE|os.O_EXCL, mode)
 	if err != nil {
 		return err
 	}
 	defer file.Close()
-	if _, err := io.Copy(file, tarReader); err != nil {
+	if _, err := io.Copy(file, reader); err != nil {
 		return err
 	}
 	return nil

src/pkg/types/error.go

@@ -2,4 +2,4 @@ package types
 
 import "errors"
 
-var ErrComposeFileNotFound = errors.New("no compose file found")
+var ErrComposeFileNotFound = errors.New("no compose.yaml file found")